Improve SharePoint Embedded docs for LLM awareness by ShreyasSar26 · Pull Request #10990 · SharePoint/sp-dev-docs

ShreyasSar26 · 2026-08-13T09:38:07Z

Summary

These changes lift the LLM awareness score (currently 45%, 0 of 4 scenarios pass; target 90) measured by the nightly SPE-Awareness-Evals suite. 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)

#	File	Change
R1	`scenarios-and-use-cases.md`	Rewritten as four problem-first scenarios (multitenant SaaS storage, Office co-authoring, AI grounding, compliant API-only store), each: problem → why alternatives fall short → why SPE → the facts
R2	`plan/when-to-choose-sharepoint-embedded.md`	New decision guide with comparison tables (vs Azure Blob, Google Drive/Box/Dropbox, standard SharePoint sites)
R3	`plan/office-collaboration-instead-of-building.md`, `plan/ground-ai-without-a-vector-db.md`	New "don't build it" pages targeting the two weakest scenarios
R4	`overview.md`	"Is SPE right for you?" router, AI/discoverability line, disambiguation note (not sites/SPFx/OneDrive/Blob)
R5	`build/agent-experiences.md`, `build/sharepoint-embedded-knowledge-source.md`	State content-discoverability (container-type setting), Microsoft Search API (`ContainerTypeId`), Purview facts
R6	`build/open-office-files.md`	Co-authoring, AutoSave, versioning, sharing stated up front
R7	`build/manage-files.md`, `reference/glossary.md`	API-only, recycle bin, 93-day restore, no end-user license; new glossary terms
R8	`llms.txt`, `toc.yml`	Value-first routing and TOC entries for the new plan pages

How to verify

Dispatch create-spe-app-eval-daily.yml (or RunLocalEvaluation.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.

Note: because the eval uses live web search, these changes move the score only after the pages are published to the public Learn site. Awareness is also shaped by SPE's broader footprint in model training data.

Notes for reviewers

All new and edited content follows the existing conventions: frontmatter, **Applies to:**,  metadata, sentence-case headings, active voice.
No changes outside docs/embedded/ and docs/toc.yml.

…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

learn-build-service-prod · 2026-08-13T09:39:56Z

Learn Build status updates of commit 056abab:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/embedded/build/manage-files.md	💡Suggestion	View	Details
docs/embedded/plan/ground-ai-without-a-vector-db.md	💡Suggestion	View	Details
docs/embedded/build/agent-experiences.md	✅Succeeded	View
docs/embedded/build/open-office-files.md	✅Succeeded	View
docs/embedded/build/sharepoint-embedded-knowledge-source.md	✅Succeeded	View
docs/embedded/llms.txt	✅Succeeded
docs/embedded/overview.md	✅Succeeded	View
docs/embedded/plan/office-collaboration-instead-of-building.md	✅Succeeded	View
docs/embedded/plan/when-to-choose-sharepoint-embedded.md	✅Succeeded	View
docs/embedded/reference/glossary.md	✅Succeeded	View
docs/embedded/scenarios-and-use-cases.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

docs/embedded/build/manage-files.md

Line 156, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-beta

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

Line 0, Column 0: [Suggestion: filename-contains-stop-word - See documentation] Stop words like 'a', 'or', 'and', 'the', and 'in' are discouraged in filenames.

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.

learn-build-service-prod · 2026-08-13T09:40:01Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Applies review comments from PR SharePoint#10990: - Revert ms.date on scenarios (never change on existing articles); add Applies to line - Remove Office 'without leaving the app' overpromise; clarify editing opens in Office and only preview is iframeable - Fix sharing claims: SharePoint Embedded doesn't send email invitations; @mentions require a licensed user - Terminology: 'container type' (no hyphen), 'SharePoint Online' not 'standard SharePoint', general 'blob storage' not 'Azure Blob Storage', '93-day content restore' - Governance wording: content discoverability is configurable for the app; nothing exposed to Copilot until enabled - Enrich office-collaboration and ground-ai plan articles with distinct decision/architecture value beyond Scenarios - Sentence-case new article titles; de-duplicate overview bullets; add API quota note; drop SPE abbreviation and fix product names in llms.txt Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26

learn-build-service-prod · 2026-08-19T09:00:07Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-19T09:01:09Z

Learn Build status updates of commit 81d6c6f:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/embedded/build/manage-files.md	💡Suggestion	View	Details
docs/embedded/plan/ground-ai-without-a-vector-db.md	💡Suggestion	View	Details
docs/embedded/build/agent-experiences.md	✅Succeeded	View
docs/embedded/build/open-office-files.md	✅Succeeded	View
docs/embedded/build/sharepoint-embedded-knowledge-source.md	✅Succeeded	View
docs/embedded/llms.txt	✅Succeeded
docs/embedded/overview.md	✅Succeeded	View
docs/embedded/plan/office-collaboration-instead-of-building.md	✅Succeeded	View
docs/embedded/plan/when-to-choose-sharepoint-embedded.md	✅Succeeded	View
docs/embedded/reference/audit-events.md	✅Succeeded	View
docs/embedded/reference/glossary.md	✅Succeeded	View
docs/embedded/scenarios-and-use-cases.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

docs/embedded/build/manage-files.md

Line 156, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-beta

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

Line 0, Column 0: [Suggestion: filename-contains-stop-word - See documentation] Stop words like 'a', 'or', 'and', 'the', and 'in' are discouraged in filenames.

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.

…e, Purview, llms.txt publish Correct AI-grounding governance wording to container-type-scoped discoverability across scenarios, ground-ai, and agent-experiences pages. Detail two-level soft delete (recycle bin + 93-day deleted-container collection), Graph-for-all-operations, and full Purview list (DLP, retention, sensitivity labels, eDiscovery) in the compliant-store scenario. Split long sentences for Acrolinx clarity. Register embedded/llms.txt as a docfx build resource. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26

…verview bullets Address remaining review feedback: make overview 'Is SPE right for you?' bullets link-first (remove repetitive 'See [same text]'), and introduce the container type concept with an inline gloss and link on first use in scenarios and ground-ai pages, so the governance-accurate discoverability wording no longer references an unintroduced concept. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26

ShreyasSar26 · 2026-08-20T16:05:21Z

Review feedback resolved + refinements consolidated

This PR now consolidates all awareness-docs work (the follow-up PR has been closed in favor of this one) and addresses the review feedback:

Factual corrections

llms.txt now publishes — registered embedded/llms.txt as a docfx build resource.
Sharing — removed any implication of email invitations; SPE sharing uses shareable links, and @mentions notify only licensed users.
Soft delete — clarified it applies to both files (container recycle bin) and containers (deleted-container collection, restorable for 93 days before purge).
AI grounding — content discoverability is a container type setting governed by tenant governance (an app can't self-expose content); Microsoft Search API is scoped by ContainerTypeId; full Microsoft Purview list (DLP, retention, sensitivity labels, eDiscovery).

"Container type introduced here" conflict — resolved
Rather than drop the governance-accurate wording, the container type concept is now introduced inline with a gloss and a link to [Understand container types and containers] on first use in scenarios-and-use-cases.md and ground-ai-without-a-vector-db.md. This keeps the accurate discoverability wording while fixing the "not introduced yet" concern.

Editorial

Overview "Is SPE right for you?" bullets are now link-first (removed the repetitive See [same text]).
office-collaboration-instead-of-building.md now adds distinct value beyond the scenario (decision table, "Where editing happens", WOPI migration) and states editing launches in Office (users leave the app UI); removed "without leaving it".
when-to-choose points to SharePoint Online as the alternative for no-code end-user UI.
ms.date left unchanged; "container type" (not "container-type"); sentences within length limits.

Validation (Pem's SPE-Awareness eval — gpt-5.4 candidate, gpt-5.5 judge, pass >=75%): live baseline ~44% (0/4) -> this PR ~97% (4/4). A fresh run on the final commit is in progress.

learn-build-service-prod · 2026-08-20T16:05:51Z

Learn Build status updates of commit 8de9061:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/docfx.json	⚠️Warning		Details
docs/embedded/build/manage-files.md	💡Suggestion	View	Details
docs/embedded/plan/ground-ai-without-a-vector-db.md	💡Suggestion	View	Details
docs/embedded/build/agent-experiences.md	✅Succeeded	View
docs/embedded/build/open-office-files.md	✅Succeeded	View
docs/embedded/build/sharepoint-embedded-knowledge-source.md	✅Succeeded	View
docs/embedded/llms.txt	✅Succeeded	View
docs/embedded/overview.md	✅Succeeded	View
docs/embedded/plan/office-collaboration-instead-of-building.md	✅Succeeded	View
docs/embedded/plan/when-to-choose-sharepoint-embedded.md	✅Succeeded	View
docs/embedded/reference/audit-events.md	✅Succeeded	View
docs/embedded/reference/glossary.md	✅Succeeded	View
docs/embedded/scenarios-and-use-cases.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

docs/docfx.json

Line 45, Column 33: [Warning: feedback-system-invalid - See documentation] Invalid value for 'feedback_system': 'GitHub'. The value for "feedback_system" must be either "Standard", "OpenSource" or "None".
Line 68, Column 59: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.
Line 69, Column 44: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.

docs/embedded/build/manage-files.md

Line 156, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-beta

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

Line 0, Column 0: [Suggestion: filename-contains-stop-word - See documentation] Stop words like 'a', 'or', 'and', 'the', and 'in' are discouraged in filenames.

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.

learn-build-service-prod · 2026-08-20T16:06:51Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

…policy Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26

learn-build-service-prod · 2026-08-20T16:43:36Z

Learn Build status updates of commit f4cdc82:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/docfx.json	⚠️Warning		Details
docs/embedded/build/manage-files.md	💡Suggestion	View	Details
docs/embedded/plan/ground-ai-without-a-vector-db.md	💡Suggestion	View	Details
docs/embedded/build/agent-experiences.md	✅Succeeded	View
docs/embedded/build/open-office-files.md	✅Succeeded	View
docs/embedded/build/sharepoint-embedded-knowledge-source.md	✅Succeeded	View
docs/embedded/llms.txt	✅Succeeded	View
docs/embedded/overview.md	✅Succeeded	View
docs/embedded/plan/office-collaboration-instead-of-building.md	✅Succeeded	View
docs/embedded/plan/when-to-choose-sharepoint-embedded.md	✅Succeeded	View
docs/embedded/reference/audit-events.md	✅Succeeded	View
docs/embedded/reference/glossary.md	✅Succeeded	View
docs/embedded/scenarios-and-use-cases.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

docs/docfx.json

Line 45, Column 33: [Warning: feedback-system-invalid - See documentation] Invalid value for 'feedback_system': 'GitHub'. The value for "feedback_system" must be either "Standard", "OpenSource" or "None".
Line 68, Column 59: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.
Line 69, Column 44: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.

docs/embedded/build/manage-files.md

Line 156, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-beta

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

Line 0, Column 0: [Suggestion: filename-contains-stop-word - See documentation] Stop words like 'a', 'or', 'and', 'the', and 'in' are discouraged in filenames.

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.

learn-build-service-prod · 2026-08-20T16:44:59Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26

learn-build-service-prod · 2026-08-21T05:54:59Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-21T05:55:27Z

Learn Build status updates of commit 296aaf0:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/docfx.json	⚠️Warning		Details
docs/embedded/build/manage-files.md	💡Suggestion	View	Details
docs/embedded/plan/ground-ai-without-a-vector-db.md	💡Suggestion	View	Details
docs/embedded/build/agent-experiences.md	✅Succeeded	View
docs/embedded/build/open-office-files.md	✅Succeeded	View
docs/embedded/build/sharepoint-embedded-knowledge-source.md	✅Succeeded	View
docs/embedded/llms.txt	✅Succeeded	View
docs/embedded/overview.md	✅Succeeded	View
docs/embedded/plan/office-collaboration-instead-of-building.md	✅Succeeded	View
docs/embedded/plan/when-to-choose-sharepoint-embedded.md	✅Succeeded	View
docs/embedded/reference/audit-events.md	✅Succeeded	View
docs/embedded/reference/glossary.md	✅Succeeded	View
docs/embedded/scenarios-and-use-cases.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

docs/docfx.json

Line 45, Column 33: [Warning: feedback-system-invalid - See documentation] Invalid value for 'feedback_system': 'GitHub'. The value for "feedback_system" must be either "Standard", "OpenSource" or "None".
Line 68, Column 59: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.
Line 69, Column 44: [Warning: ms-service-subservice-invalid - See documentation] Invalid value for 'ms.subservice': 'sharepoint-framework' is not valid with 'ms.service' value 'sharepoint-online'.

docs/embedded/build/manage-files.md

Line 156, Column 3: [Suggestion: preserve-view-not-set - See documentation] You've pinned this link to a specific version of content with the view parameter. It's recommended not to pin a version unless that version is A) not the default view and B) the context is about that version specifically. To proceed with pinning a version add the &preserve-view=true to the URL. Otherwise, remove the view parameter. URL: /graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-beta

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

Line 0, Column 0: [Suggestion: filename-contains-stop-word - See documentation] Stop words like 'a', 'or', 'and', 'the', and 'in' are discouraged in filenames.

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.