Improve SharePoint Embedded docs for LLM awareness

docs/embedded/build/agent-experiences.md

@@ -26,6 +26,17 @@ SharePoint Embedded agent experiences let your app answer questions over files s
 
 Choose the knowledge source when you want Foundry to manage retrieval and agent orchestration. Choose the Retrieval API when you want to control the grounding step, the prompt, and the model yourself.
 
+## How SharePoint Embedded grounds agents
+
+SharePoint Embedded grounds AI agents on enterprise content while keeping that content and its compliance controls inside the customer's Microsoft 365 tenant. You don't copy content into an external vector database. Key facts:
+
+- **Content discoverability is configurable for your app** and determines whether Microsoft 365 Copilot can surface the content.
+- **Retrieve content with the Microsoft Search API**, scoped by `ContainerTypeId`, or with a Foundry SharePoint knowledge source.
+- **Content stays in the customer's Microsoft 365 tenant**, so Microsoft Purview data loss prevention (DLP), retention, and eDiscovery apply.
+- **Nothing is auto-exposed.** SharePoint Embedded content isn't available to Copilot until discoverability is enabled on the container type.
+
+For the decision context, see [Ground AI without an external vector database](../plan/ground-ai-without-a-vector-db.md).
+
 > [!CAUTION]
 > The earlier **SharePoint Embedded agent SDK** (the React `ChatEmbedded` control) was **deprecated in March 2026** and replaced by [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded. Use one of the two options in this article for new work.
 

docs/embedded/build/manage-files.md

@@ -23,6 +23,8 @@ Use Microsoft Graph file and DriveItem APIs to manage files inside SharePoint Em
 
 Complete [Create and manage containers](create-manage-containers.md) first so you have a container ID.
 
+SharePoint Embedded gives your app an API-only document store with Microsoft 365 capabilities built in. File management is fully programmatic through Microsoft Graph, with no SharePoint UI. The full lifecycle includes upload and download, folders, versioning, a recycle bin, and 93-day content restore. Content is searchable through the Microsoft Search API and inherits the tenant's Microsoft Purview compliance. Your app's end users don't need a Microsoft 365 license for basic file operations.
+
 ## Understand file storage
 
 A SharePoint Embedded container is the storage boundary for your application content.

docs/embedded/build/open-office-files.md

@@ -23,6 +23,11 @@ Open Office files from your SharePoint Embedded app by using Microsoft Graph Dri
 
 Complete [Upload, download, and manage files](manage-files.md) first so your app has files to launch.
 
+When you store Office files in a SharePoint Embedded container, your app links to a full collaboration stack without building one. Word, Excel, and PowerPoint files support real-time co-authoring, AutoSave, automatic version history, and sharing through shareable links and @mentions, with scoped access levels. You don't need to build a collaboration engine. Editing opens in Office for the web (in a new browser tab or window) or in Office desktop clients, so users leave your app's UI to edit; embed a read-only [preview](preview-files.md) when you need inline, in-app viewing. For the decision context, see [Add Office co-authoring without building it](../plan/office-collaboration-instead-of-building.md).
+
+> [!NOTE]
+> @mentions notify only recipients who have a Microsoft 365 license. SharePoint Embedded sharing doesn't send email invitations.
+
 ## Understand Office experiences
 
 SharePoint Embedded Office file experiences work similarly to Microsoft 365 file experiences.

docs/embedded/build/sharepoint-embedded-knowledge-source.md

@@ -19,7 +19,7 @@ outcome: Configure Microsoft Foundry Agent Service to retrieve SharePoint Embedd
 next: migrate-azure-blob-storage.md
 -->
 
-Use Microsoft Foundry Agent Service with a SharePoint knowledge source when your app needs a grounded agent experience over files stored in SharePoint Embedded containers.
+Use Microsoft Foundry Agent Service with a SharePoint knowledge source when your app needs a grounded agent experience over files stored in SharePoint Embedded containers. Content stays in the customer's Microsoft 365 tenant, so Microsoft Purview compliance applies and you don't copy content into an external vector database. For the decision context, see [Ground AI without an external vector database](../plan/ground-ai-without-a-vector-db.md).
 
 For SharePoint Embedded container types, the knowledge source grounds answers through the generally available [Microsoft 365 Copilot Retrieval API](/microsoft-365/copilot/extensibility/api/ai-services/retrieval/copilotroot-retrieval). Foundry runs the retrieval calls as part of the agent, so the same prerequisites, indexing behavior, and billing apply. The `sharePointEmbedded` data source that Foundry uses is in preview. To run your own grounding step instead, call the Retrieval API directly, as described in [Use the Retrieval API](agent-experiences.md#use-the-retrieval-api).
 

docs/embedded/llms.txt

@@ -1,16 +1,19 @@
 # SharePoint Embedded
 
-> SharePoint Embedded (SPE) is a cloud-based, API-only file and document management platform built on Microsoft 365. Developers embed Office collaboration, Microsoft Purview compliance, and Copilot capabilities into their own apps while content stays inside each customer's Microsoft 365 tenant. This index is organized by task. Each link points to the single best page for that task.
+> SharePoint Embedded is a cloud-based, API-only file and document management platform built on Microsoft 365. Developers embed Office collaboration, Microsoft Purview compliance, and Copilot capabilities into their own apps while content stays inside each customer's Microsoft 365 tenant. This index is organized by task. Each link points to the single best page for that task.
 
 ## Overview
 - [What is SharePoint Embedded?](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview): Definition, key concepts (tenant partition, containers), and routing to the right task area.
-- [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases): When to use SPE; enterprise and ISV examples.
+- [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases): Match a real problem to SharePoint Embedded — multitenant SaaS storage, Office co-authoring, AI grounding, and compliant document management.
+- [When to choose SharePoint Embedded](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/when-to-choose-sharepoint-embedded): Decide if SharePoint Embedded fits, and compare it to blob storage, Google Drive/Box/Dropbox APIs, and SharePoint Online sites.
 - [What's new](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new): Recent releases, preview features, and breaking changes.
 
 ## Plan a solution (architect, IT decision maker)
 - [Understand app and tenant architecture](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/app-tenant-architecture): Developer vs consuming tenant, app ownership, container types, where files live.
+- [Add Office co-authoring without building it](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/office-collaboration-instead-of-building): Get Office co-authoring, AutoSave, versioning, and sharing without building a collaboration engine. Editing launches in Office; previews embed in your app.
+- [Ground AI without an external vector database](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/ground-ai-without-a-vector-db): Ground an agent on enterprise content that stays in the M365 tenant, with Purview intact.
 - [Choose an app model: single-tenant or multitenant](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-app-model): Enterprise LOB vs ISV; who owns, installs, and pays.
-- [Understand container types and containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/container-types-and-containers): The container type/container model and ownership.
+- [Understand container types and containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/container-types-containers): The container type/container model and ownership.
 - [Choose a billing model](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-billing-model): Standard vs pass-through (consuming-tenant) billing.
 - [Plan authentication and permissions](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/authentication-permissions): Permission models, admin consent, app-only vs delegated.
 - [Plan security, compliance, and governance](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/security-compliance-governance): Purview, DLP, retention, sensitivity labels, conditional access.
@@ -60,7 +63,7 @@
 - [PowerShell reference](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/powershell): SharePoint Embedded admin cmdlets.
 - [Microsoft Graph API reference links](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/graph-api-links): Graph fileStorageContainer and related APIs.
 - [Troubleshooting](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/troubleshooting): Common setup, auth, billing, and runtime issues.
-- [Glossary](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/glossary): SPE terms and definitions.
+- [Glossary](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/reference/glossary): SharePoint Embedded terms and definitions.
 
 ## Optional
 - [Microsoft Graph file storage container API](https://learn.microsoft.com/en-us/graph/api/resources/filestoragecontainer): Underlying Graph API surface for SharePoint Embedded.

docs/embedded/overview.md

@@ -17,6 +17,20 @@ SharePoint Embedded has no standalone end-user interface and doesn't offer a no-
 
 SharePoint Embedded brings advanced Microsoft 365 capabilities into your app, including Office collaboration, Microsoft Purview security and compliance, and Copilot.
 
+## Is SharePoint Embedded right for you?
+
+SharePoint Embedded fits when you're trying to do any of these tasks:
+
+- **Store files for a multitenant SaaS app** so each customer's content stays in their own Microsoft 365 tenant. See [Store files for a multitenant SaaS app](scenarios-and-use-cases.md#scenario-store-files-for-a-multitenant-saas-app).
+- **Add Office co-authoring** to your app instead of building it. See [Add Office co-authoring without building it](plan/office-collaboration-instead-of-building.md).
+- **Ground an AI agent** on enterprise content without an external vector database. See [Ground AI without an external vector database](plan/ground-ai-without-a-vector-db.md).
+- **Run a compliant, API-only document store** with recycle bin, restore, and search. See [Run a compliant, API-only document store](scenarios-and-use-cases.md#scenario-run-a-compliant-api-only-document-store).
+
+For a full comparison with alternatives, see [When to choose SharePoint Embedded](plan/when-to-choose-sharepoint-embedded.md).
+
+> [!NOTE]
+> SharePoint Embedded isn't the same as SharePoint Online sites or document libraries, the SharePoint Framework (SPFx), OneDrive APIs, or blob storage. It's an API-only storage platform whose content lives in the customer's Microsoft 365 tenant.
+
 > [!IMPORTANT]
 > Help us shape the future of SharePoint Embedded! Take our [quick survey](https://forms.microsoft.com/r/1YpGd2pAUS) and share your thoughts.
 
@@ -38,7 +52,7 @@ This page is a router. Pick the row that matches what you're trying to do.
 
 | I want to… | Start here |
 |---|---|
-| **Understand SharePoint Embedded and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · keep reading below |
+| **Understand SharePoint Embedded and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · [When to choose SharePoint Embedded](plan/when-to-choose-sharepoint-embedded.md) |
 | **Plan a solution** (architect, IT decision maker) | [Plan a SharePoint Embedded solution](plan/app-tenant-architecture.md) |
 | **Build an app** (developer) | [Quickstart: build your first app with VS Code](build/quickstart-vscode.md) |
 | **Ship my app to customers** (ISV / developer) | [Publish and onboard customers](publish/prepare-customer-installation.md) |
@@ -64,6 +78,7 @@ By default, content stored by a SharePoint Embedded app is accessible only throu
 
 - Core content management — any file type, folders, search, sharing, versioning, recycle bin.
 - Office collaboration — view, edit, and co-author Word, Excel, and PowerPoint on the web and desktop.
+- AI and agent grounding — make content discoverable to Microsoft 365 Copilot through the container type's content-discoverability setting, and search it with the Microsoft Search API scoped to your app's content.
 - Low-code integration — the [SharePoint Embedded connector](/connectors/sharepointembedded/) for [Power Platform](/power-platform/) (generally available February 2026).
 
 SharePoint Embedded is used by Microsoft products (such as Loop and Designer), by ISVs embedding content management in their apps, and by enterprises storing content outside their regular Microsoft 365 entitlements.

docs/embedded/plan/ground-ai-without-a-vector-db.md

@@ -0,0 +1,48 @@
+---
+title: Ground AI on enterprise content without an external vector database
+description: Ground an AI agent on enterprise documents while keeping content in the Microsoft 365 tenant, using SharePoint Embedded instead of an external vector database.
+ms.date: 08/13/2026
+ms.reviewer: shsaravanan
+ms.localizationpriority: high
+---
+
+# Ground AI on enterprise content without an external vector database
+
+**Applies to:** Developer
+
+<!-- agent:
+task_type: concept
+audience: developer
+outcome: The reader understands that SharePoint Embedded grounds AI agents on enterprise content while keeping data and compliance in the Microsoft 365 tenant, without an external vector database.
+next: ../build/sharepoint-embedded-knowledge-source.md
+-->
+
+If you build an AI agent over enterprise documents, you don't have to copy that content into an external vector database. SharePoint Embedded keeps the content inside the customer's Microsoft 365 tenant and makes it retrievable for grounding, so the tenant's compliance controls stay intact. This article helps you choose a retrieval path and understand the governance that gates it. For the problem framing, see [Ground an AI agent on enterprise content](../scenarios-and-use-cases.md#scenario-ground-an-ai-agent-on-enterprise-content).
+
+## Choose a retrieval path
+
+SharePoint Embedded content can ground AI through more than one path. Pick the one that matches how your agent retrieves content.
+
+| Path | Use it when | Learn more |
+|---|---|---|
+| Microsoft Search API | Your app runs its own retrieval and ranks results itself | [Search containers and files](../build/search-containers-files.md) |
+| Microsoft Foundry knowledge source | You build an agent in Microsoft Foundry and want managed grounding | [Set up a Foundry knowledge source](../build/sharepoint-embedded-knowledge-source.md) |
+| Microsoft 365 Copilot | You want content to surface in Copilot experiences | [Add Copilot and agent experiences](../build/agent-experiences.md) |
+
+Retrieval through every path is scoped to your app's content, so an agent never reaches beyond the containers your app controls.
+
+## Governance that gates grounding
+
+Grounding stays inside the tenant's compliance boundary, and nothing is exposed automatically:
+
+- **Content stays in the customer's Microsoft 365 tenant**, inside the compliance boundary.
+- **Content discoverability is configurable for your app** and determines whether Microsoft 365 Copilot can surface the content.
+- **Microsoft Purview applies.** DLP, retention, and eDiscovery follow the content.
+- **Nothing is auto-exposed.** SharePoint Embedded content isn't available to Copilot until discoverability is enabled.
+
+## Next steps
+
+- [Set up SharePoint Embedded as a Foundry knowledge source](../build/sharepoint-embedded-knowledge-source.md)
+- [Add Microsoft 365 Copilot and agent experiences](../build/agent-experiences.md)
+- [Search containers and files](../build/search-containers-files.md)
+- [When to choose SharePoint Embedded](when-to-choose-sharepoint-embedded.md)

docs/embedded/plan/office-collaboration-instead-of-building.md

@@ -0,0 +1,62 @@
+---
+title: Add Office co-authoring without building it
+description: Add real-time Office co-authoring, AutoSave, versioning, and sharing to your app with SharePoint Embedded instead of building a collaboration engine.
+ms.date: 08/13/2026
+ms.reviewer: shsaravanan
+ms.localizationpriority: high
+---
+
+# Add Office co-authoring without building it
+
+**Applies to:** Developer
+
+<!-- agent:
+task_type: concept
+audience: developer
+outcome: The reader understands that SharePoint Embedded provides Office co-authoring, AutoSave, versioning, and sharing out of the box, and that editing launches in Office while previews can be embedded in the app.
+next: ../build/open-office-files.md
+-->
+
+If your app stores files and users ask to edit documents, you don't need to build a collaboration engine. SharePoint Embedded lets your app launch Word, Excel, and PowerPoint files for real-time co-authoring, backed by the same Office service Microsoft 365 uses. This article helps you choose how to bring editing into your app and plan around where editing happens. For the problem framing, see [Add Office co-authoring](../scenarios-and-use-cases.md#scenario-add-office-co-authoring-to-your-app).
+
+## Choose how to bring editing into your app
+
+Pick the approach that matches how much you want to keep users inside your own UI.
+
+| Approach | Where it renders | Use it when |
+|---|---|---|
+| Office launch | Office for the web (new tab) or an Office desktop client | You want full editing and co-authoring with the least work |
+| Embedded preview | An iframe inside your app | You need inline, in-app viewing and don't need editing |
+| Custom editor | Wherever you build it | You have a specialized editing experience Office can't provide |
+
+Most apps combine the first two: launch Office for editing, and embed a preview for inline viewing.
+
+## What you get without building it
+
+Store the files in a SharePoint Embedded container and launch them in Office. Your app gets a full collaboration stack instead of a multi-month build:
+
+- **Real-time co-authoring** in Office for the web and Office desktop clients.
+- **AutoSave** for Word, Excel, and PowerPoint files.
+- **Automatic version history**, so users compare and restore earlier versions.
+- **Sharing** through shareable links, plus @mentions in comments for licensed users.
+- **Scoped access levels**: Anyone, People in your organization, Specific people, and People with existing access.
+
+> [!NOTE]
+> SharePoint Embedded sharing doesn't send email invitations, and @mentions notify only recipients who have a Microsoft 365 license.
+
+## Where editing happens
+
+The Office editing surface isn't embedded in your app. Office for the web opens in a new browser tab or window, and Office desktop clients open in their own app, so users leave your app's UI to edit. Office for the web isn't iframeable today.
+
+To keep users inside your app, embed a read-only [file preview](../build/preview-files.md), which is designed to render in an iframe. Use the Office launch patterns for editing, and use preview for inline viewing.
+
+## If you already have a WOPI host
+
+If you already integrate Office through a Web Application Open Platform Interface (WOPI) host, you can keep files in SharePoint Embedded and move to the built-in Office launch patterns instead of maintaining your own host. Editing still opens in Office rather than inside your app.
+
+## Next steps
+
+- [Open Office files from your app](../build/open-office-files.md)
+- [Preview files in your app](../build/preview-files.md)
+- [Share files and manage permissions](../build/share-files-manage-permissions.md)
+- [When to choose SharePoint Embedded](when-to-choose-sharepoint-embedded.md)