Improve SharePoint Embedded docs for LLM awareness - #10990
Open
ShreyasSar26 wants to merge 1 commit into
Open
Conversation
…d assertion facts Rewrites the front-door docs so models recommend SharePoint Embedded for real developer problems, and states the graded facts on the pages agents land on. - Rewrite scenarios-and-use-cases.md as four problem-first scenarios (R1) - Add plan/when-to-choose-sharepoint-embedded.md with comparison tables (R2) - Add plan/office-collaboration-instead-of-building.md and plan/ground-ai-without-a-vector-db.md (R3) - Overview: 'Is SPE right for you?' router, AI/discoverability line, disambiguation note (R4) - agent-experiences.md + knowledge-source: state discoverability, Search API, Purview facts (R5) - open-office-files.md: co-authoring, AutoSave, versioning, sharing up front (R6) - manage-files.md + glossary: API-only, recycle bin, 93-day restore, no license (R7) - llms.txt + toc.yml: value-first routing and new plan pages (R8) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26
Contributor
|
Learn Build status updates of commit 056abab: 💡 Validation status: suggestions
docs/embedded/build/manage-files.md
docs/embedded/plan/ground-ai-without-a-vector-db.md
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
Contributor
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
| @@ -4,11 +4,14 @@ | |||
|
|
|||
Contributor
There was a problem hiding this comment.
I don't think this file is published: https://learn.microsoft.com/sharepoint/dev/embedded/llms.txt
Why do we have llms.txt if it's not published?
|
|
||
| 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). |
Contributor
There was a problem hiding this comment.
This sounds repetitive. The link is the same as the bolded text.
Suggested change
| - **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). | |
| - **[Store files for a multitenant SaaS app](scenarios-and-use-cases.md#scenario-store-files-for-a-multitenant-saas-app)** so each customer's content stays in their own Microsoft 365 tenant. |
Same for the next few points
|
|
||
| - 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`. |
Contributor
There was a problem hiding this comment.
Suggested change
| - 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`. | |
| - 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. |
We haven't introduced the concept of container type at this point.
| ms.reviewer: stpuceli | ||
| title: Scenarios and Use Cases | ||
| description: Common developer problems that SharePoint Embedded solves, from multitenant SaaS storage to Office co-authoring, AI grounding, and compliant document management. | ||
| ms.date: 08/13/2026 |
Contributor
There was a problem hiding this comment.
Suggested change
| ms.date: 08/13/2026 | |
| ms.date: 07/13/2026 |
Shouldn't update ms.date (the latest skill adds this rule, by the way--make sure you're using the latest version)
|
|
||
| # Scenarios and use cases for SharePoint Embedded | ||
|
|
||
| **Applies to:** All |
Contributor
There was a problem hiding this comment.
I thought we were starting all articles with this?
|
|
||
| ### The problem | ||
|
|
||
| You build a multitenant SaaS product, such as contract management for enterprise legal teams. Your biggest blocker is file storage. Enterprise customers won't accept their documents living in your storage. Their IT teams want to apply their own data loss prevention (DLP) and retention rules. You still need full control of the files from your app: create, read, organize, permission, and delete, all through APIs. |
Contributor
There was a problem hiding this comment.
Suggested change
| You build a multitenant SaaS product, such as contract management for enterprise legal teams. Your biggest blocker is file storage. Enterprise customers won't accept their documents living in your storage. Their IT teams want to apply their own data loss prevention (DLP) and retention rules. You still need full control of the files from your app: create, read, organize, permission, and delete, all through APIs. | |
| You build a multitenant SaaS product, such as contract management for enterprise legal teams. Your biggest blocker is file storage. Enterprise customers won't accept their documents living in your storage. Their IT teams want to apply their own security and compliance policies, like data loss prevention (DLP) and retention rules. You still need full control of the files from your app: create, read, organize, permission, and delete, all through APIs. |
|
|
||
| ### The problem | ||
|
|
||
| You have a custom app, and your top feature request is "let me edit documents without leaving the app." Today you store files and hand out download links. Users want to open a Word or Excel file and co-author it in real time, with AutoSave and version history, plus sharing with an external person through a link. |
Contributor
There was a problem hiding this comment.
Suggested change
| You have a custom app, and your top feature request is "let me edit documents without leaving the app." Today you store files and hand out download links. Users want to open a Word or Excel file and co-author it in real time, with AutoSave and version history, plus sharing with an external person through a link. | |
| You have a custom app, and your top feature request is "let me edit Office documents the same way I'm used to." Today you store files and hand out download links. Perhaps you even use a Web Application Open Platform Interface (WOPI) host. But your users want to open a Word or Excel file and co-author it in real time, with AutoSave, version history, sharing, and all the features of Office for the web, Office Desktop, and Microsoft 365 for mobile. |
Key here is to remove "without leaving the app" (because of open in Office Desktop would leave the app, and Office for the web doesn't iframe)
| ### Examples | ||
| - **Real-time co-authoring** in Office for the web and Office desktop clients. | ||
| - **AutoSave** and **automatic version history** for Word, Excel, and PowerPoint. | ||
| - **Sharing** through email invitations, shareable links, and @mentions. |
Contributor
There was a problem hiding this comment.
Sharing in SPE doesn't send email invitations IIRC (by design)
@mentions only applies to licenced users
| - Deal room applications | ||
| - Shared research environments | ||
| - Content **stays in the customer's Microsoft 365 tenant**. | ||
| - **Content discoverability is a container-type setting** that controls whether Microsoft 365 Copilot can surface the content. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Content discoverability is a container-type setting** that controls whether Microsoft 365 Copilot can surface the content. | |
| - **Content discoverability is configurable for your app** and controls whether Microsoft 365 Copilot can surface the content. |
"Container type" hasn't been introduced here. Also, "container type" and not "container-type". It looks like this is missing some of the rules encoded in the doc updater skill. Let's figure out what's going on.
| - Shared research environments | ||
| - Content **stays in the customer's Microsoft 365 tenant**. | ||
| - **Content discoverability is a container-type setting** that controls whether Microsoft 365 Copilot can surface the content. | ||
| - Retrieve content with the **Microsoft Search API**, scoped by `ContainerTypeId`, or a Microsoft Foundry knowledge source. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Retrieve content with the **Microsoft Search API**, scoped by `ContainerTypeId`, or a Microsoft Foundry knowledge source. | |
| - Retrieve content with the **Microsoft Search API** or a Microsoft Foundry knowledge source, scoped to your app's content. |
| - Content **stays in the customer's Microsoft 365 tenant**. | ||
| - **Content discoverability is a container-type setting** that controls whether Microsoft 365 Copilot can surface the content. | ||
| - Retrieve content with the **Microsoft Search API**, scoped by `ContainerTypeId`, or a Microsoft Foundry knowledge source. | ||
| - **Microsoft Purview** DLP, retention, and eDiscovery apply, and nothing is exposed to Copilot until you enable discoverability. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Microsoft Purview** DLP, retention, and eDiscovery apply, and nothing is exposed to Copilot until you enable discoverability. | |
| - **Microsoft Purview** DLP, retention, and eDiscovery apply, and nothing is exposed to Copilot until discoverability is enabled. |
Refer internally to admin governance for why this wording is needed
|
|
||
| ### Why use SharePoint Embedded instead of SharePoint Online? | ||
| - **API-only** through Microsoft Graph, with no SharePoint UI to bypass. | ||
| - Full lifecycle: upload and download, folders, versioning, **recycle bin**, and **93-day container restore**. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Full lifecycle: upload and download, folders, versioning, **recycle bin**, and **93-day container restore**. | |
| - Full lifecycle: upload and download, folders, versioning, **recycle bin**, and **93-day content restore**. |
Applies to both containers and files/folders
| 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. |
Contributor
There was a problem hiding this comment.
"without leaving it" is not something SPE offers
| ms.localizationpriority: high | ||
| --- | ||
|
|
||
| # Add Office editing without building it |
Contributor
There was a problem hiding this comment.
This article isn't providing any value on top of what you added to the Scenarios and Use Cases article. Let's add some value. You're linking to this article from that other article and the reader will come to another page that says exactly the same thing.
|
|
||
| Reconsider or choose another option when: | ||
|
|
||
| - You need a **ready-made, no-code end-user UI**. SharePoint Embedded is API-only and has no interface of its own. |
Contributor
There was a problem hiding this comment.
May be a good hook for SharePoint Online instead of leaving it open.
|
|
||
| - You need a **ready-made, no-code end-user UI**. SharePoint Embedded is API-only and has no interface of its own. | ||
| - You **don't build an application**. Every SharePoint Embedded scenario involves calling Microsoft Graph from an app. | ||
| - You need collaborative sites, portals, or intranet features. Use **standard SharePoint** instead. |
Contributor
There was a problem hiding this comment.
What's "standard SharePoint". You probably mean "SharePoint Online"
I believe I saw this elsewhere and didn't flag it. Let's avoid "standard SharePoint" and use the actual product name.
| - You **don't build an application**. Every SharePoint Embedded scenario involves calling Microsoft Graph from an app. | ||
| - You need collaborative sites, portals, or intranet features. Use **standard SharePoint** instead. | ||
|
|
||
| ## SharePoint Embedded vs Azure Blob Storage |
Contributor
There was a problem hiding this comment.
Suggested change
| ## SharePoint Embedded vs Azure Blob Storage | |
| ## SharePoint Embedded vs blob storage |
Don't compare against Azure Blob Storage but in general blob storage solutions
|
|
||
| | Consideration | SharePoint Embedded | Azure Blob Storage | | ||
| |---|---|---| | ||
| | Where content lives | The customer's Microsoft 365 tenant | Your Azure subscription | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Where content lives | The customer's Microsoft 365 tenant | Your Azure subscription | | |
| | Where content lives | The customer's Microsoft 365 tenant | Your storage account | |
| |---|---|---| | ||
| | Where content lives | The customer's Microsoft 365 tenant | Your Azure subscription | | ||
| | Compliance | Inherits the customer tenant's Microsoft Purview DLP, retention, and eDiscovery | You build the compliance layer yourself | | ||
| | Office co-authoring | Built in for Word, Excel, and PowerPoint | Not available | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Office co-authoring | Built in for Word, Excel, and PowerPoint | Not available | | |
| | Office co-authoring | Built in for Word, Excel, and PowerPoint | Not generally available | |
Technically somewhat available in CSPP+ with a WOPI host, with limited capabilities
| | Consideration | SharePoint Embedded | Google Drive, Box, or Dropbox APIs | | ||
| |---|---|---| | ||
| | Data residency | Stays in the customer's Microsoft 365 tenant | Stored in the provider's cloud | | ||
| | Customer-enforced policy | Customer admin applies their own DLP and retention | Limited customer control | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Customer-enforced policy | Customer admin applies their own DLP and retention | Limited customer control | | |
| | Customer-enforced policy | Customer's existing Microsoft 365 policies apply | Limited customer control | |
| | End-user licensing | No per-seat license required for end users | Often per-seat licensing | | ||
| | Native Office editing | Built-in Word, Excel, and PowerPoint co-authoring | Conversion or add-ons required | | ||
|
|
||
| ## SharePoint Embedded vs standard SharePoint sites |
Contributor
There was a problem hiding this comment.
Suggested change
| ## SharePoint Embedded vs standard SharePoint sites | |
| ## SharePoint Embedded vs SharePoint Online sites |
| | User interface | Headless and API-only; your app owns the UX | Built-in site UI users can browse | | ||
| | Content isolation | Dedicated containers your app controls | Shared site and library structure | | ||
| | Storage entitlements | Separate, metered billing | Counts against Microsoft 365 storage | | ||
| | Bypass risk | Users can't bypass your app through a site | Users with permission can open the site directly | |
Contributor
There was a problem hiding this comment.
Add a note on API quota, higher quota for SPE
| | Owning application | The Microsoft Entra ID application registration strongly coupled with a container type; each owning app can own one container type at a time. See [app architecture](../plan/app-tenant-architecture.md). | | ||
| | Partition | The API-only SharePoint storage partition created in a consuming tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | | ||
| | Partition | The API-only SharePoint storage partition created in a consumer's Microsoft 365 tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | | ||
| | Content discoverability | A container type setting that controls whether content in its containers can surface in Microsoft 365 experiences, including Microsoft 365 Copilot. See [add Copilot and agent experiences](../build/agent-experiences.md). | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Content discoverability | A container type setting that controls whether content in its containers can surface in Microsoft 365 experiences, including Microsoft 365 Copilot. See [add Copilot and agent experiences](../build/agent-experiences.md). | | |
| | Content discoverability | A SharePoint Embedded app setting that controls whether its content can surface in Microsoft 365 experiences, including Microsoft 365 Copilot. See [add Copilot and agent experiences](../build/agent-experiences.md). | |
| | Partition | The API-only SharePoint storage partition created in a consumer's Microsoft 365 tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | | ||
| | Content discoverability | A container type setting that controls whether content in its containers can surface in Microsoft 365 experiences, including Microsoft 365 Copilot. See [add Copilot and agent experiences](../build/agent-experiences.md). | | ||
| | Recycle bin | Storage for soft-deleted files in a container, so users can restore items before permanent deletion. See [upload, download, and manage files](../build/manage-files.md). | | ||
| | Container restore | Recovery of a deleted container within 93 days of deletion, before permanent removal. See [archive and restore containers](../build/archive-restore-containers.md). | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Container restore | Recovery of a deleted container within 93 days of deletion, before permanent removal. See [archive and restore containers](../build/archive-restore-containers.md). | | |
| | Content restore | Recovery of deleted content within 93 days of deletion, before permanent removal. See [archive and restore containers](../build/archive-restore-containers.md). | |
| ms.localizationpriority: high | ||
| --- | ||
|
|
||
| # Ground AI on enterprise content without an external vector database |
Contributor
There was a problem hiding this comment.
Same as the office collaboration article. It doesn't provide more value than what's already in Scenarios and Use Cases.
|
|
||
| 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). |
Contributor
There was a problem hiding this comment.
@mentions require user licence FYI, probably good to not overpromise (maybe add a disclaimer)
Andrew Connell (andrewconnell)
added
the
pr:awaiting-peer-reviews
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
These changes lift the LLM awareness score (currently 45%, 0 of 4 scenarios pass; target 90) measured by the nightly
SPE-Awareness-Evalssuite. That eval asks a model — unaided, with web search — to solve four realistic developer problems that never name SharePoint Embedded (SPE), and scores how often it recommends SPE on its own and states the right facts.The gap is positioning at the front door, not doc quality. This PR reframes the entry content around real problems, adds the missing "when to choose SPE / vs alternatives" content, and states the graded facts on the pages agents land on.
Changes (8 recommendations)
scenarios-and-use-cases.mdplan/when-to-choose-sharepoint-embedded.mdplan/office-collaboration-instead-of-building.md,plan/ground-ai-without-a-vector-db.mdoverview.mdbuild/agent-experiences.md,build/sharepoint-embedded-knowledge-source.mdContainerTypeId), Purview factsbuild/open-office-files.mdbuild/manage-files.md,reference/glossary.mdllms.txt,toc.ymlHow to verify
Dispatch
create-spe-app-eval-daily.yml(orRunLocalEvaluation.ps1 -EvalFiles evals/SPE-Awareness-Evals.json), 5 rounds × all models. Watch each scenario clear 70% (pass) then 75% (strong); target overall ≥ 90, 4/4 pass.Notes for reviewers
**Applies to:**,<!-- agent: -->metadata, sentence-case headings, active voice.docs/embedded/anddocs/toc.yml.