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 a container-type setting.** You control whether Microsoft 365 Copilot can surface content from a container type.
+- **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 you enable discoverability 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 container 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,8 @@ 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 gets a full collaboration stack without building one. Word, Excel, and PowerPoint files support real-time co-authoring, AutoSave, automatic version history, and sharing through email invitations, shareable links, and @mentions, with scoped access levels. You don't need to build a collaboration engine. For the decision context, see [Add Office editing without building it](../plan/office-collaboration-instead-of-building.md).
+
 ## 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

@@ -4,11 +4,14 @@
 
 ## 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 SPE — 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 SPE fits, and compare it to Azure Blob, Google Drive/Box/Dropbox APIs, and standard SharePoint 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 editing 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.
+- [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.
 - [Choose a billing model](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-billing-model): Standard vs pass-through (consuming-tenant) billing.

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 editing and co-authoring** to your app instead of building it. See [Add Office editing 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 standard SharePoint sites or document libraries, the SharePoint Framework (SPFx), OneDrive APIs, or Azure 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 by `ContainerTypeId`.
 - 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,47 @@
+---
+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.
+
+## The problem
+
+You build an "ask the knowledge base" agent over thousands of internal documents. You want to consolidate them, make them searchable, and use them to ground a large language model (LLM). But security teams reject copying content into an external vector database, and the content must keep its retention and eDiscovery controls.
+
+## Why an external vector database falls short
+
+- **It moves data out of the tenant.** Copying documents into a third-party store breaks the compliance boundary.
+- **You rebuild compliance.** Retention, eDiscovery, and data loss prevention (DLP) don't follow the copy.
+- **You maintain a pipeline.** Sync, re-indexing, and access trimming become your ongoing responsibility.
+
+## Why SharePoint Embedded
+
+Store the documents in SharePoint Embedded containers and ground your agent on them in place:
+
+- **Content stays in the customer's Microsoft 365 tenant**, inside the compliance boundary.
+- **Content discoverability is a container-type setting.** You control whether Microsoft 365 Copilot can surface content from a container type.
+- **Retrieve with the Microsoft Search API**, scoped by `ContainerTypeId`, or with a Microsoft Foundry SharePoint knowledge source.
+- **Microsoft Purview applies.** DLP, retention, and eDiscovery follow the content.
+- **Nothing is auto-exposed.** SharePoint Embedded content isn't available to Copilot until you enable discoverability.
+
+## 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,46 @@
+---
+title: Add Office Editing 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 editing 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, instead of building a collaboration engine.
+next: ../build/open-office-files.md
+-->
+
+If your app stores files and users ask to edit documents without leaving it, you don't need to build a collaboration engine. SharePoint Embedded lets your app open Word, Excel, and PowerPoint files for real-time co-authoring, backed by the same Office service Microsoft 365 uses.
+
+## The problem
+
+Your app stores files, often as download links to blob storage. Users want to click a Word or Excel file and edit it together, in real time, right inside your app. Building this yourself with conflict-free replicated data types (CRDTs) takes months, and it still doesn't render native Office formats.
+
+## Why building it yourself falls short
+
+- **Real-time editing is hard.** Co-authoring, presence, and conflict resolution take significant engineering effort.
+- **Native Office rendering is separate.** Even a working editor doesn't open `.docx`, `.xlsx`, or `.pptx` with full fidelity.
+- **Versioning and recovery add more work.** AutoSave, version history, and restore each need their own design.
+
+## Why SharePoint Embedded
+
+Store the files in a SharePoint Embedded container and open them through Office. Your app gets a full collaboration stack without building one:
+
+- **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 email invitations, shareable links, and @mentions in comments.
+- **Scoped access levels**: Anyone, People in your organization, Specific people, and People with existing access.
+
+## Next steps
+
+- [Open Office files from your app](../build/open-office-files.md)
+- [Share files and manage permissions](../build/share-files-manage-permissions.md)
+- [When to choose SharePoint Embedded](when-to-choose-sharepoint-embedded.md)