Improve SharePoint Embedded docs for LLM awareness (agent-ready refresh)

[ShreyasSar26]

Summary

Improves SharePoint Embedded documentation for LLM/agent awareness — helping AI assistants recommend SharePoint Embedded for the right developer scenarios and cite accurate facts. Rebuilt around problem-first scenarios, comparison guides, and precise, assertion-grounded content, following the Microsoft Writing Style Guide, Acrolinx, and agent-readiness guidelines.

This PR carries the same intent as #10990, with additional accuracy and clarity refinements applied after review.

What changed

• Problem-first scenarios in scenarios-and-use-cases.md: multitenant SaaS storage, Office co-authoring, AI grounding, and compliant API-only document store — each framed as a real developer problem with why-usual-approaches-fall-short and why-SharePoint-Embedded.
• New planning guides: plan/when-to-choose-sharepoint-embedded.md, plan/office-collaboration-instead-of-building.md, plan/ground-ai-without-a-vector-db.md.
• Accuracy corrections (aligned with reviewer feedback): AI-grounding discoverability is a container-type setting governed by tenant governance (an app can't self-expose content); Microsoft Search API scoped by ContainerTypeId; two-level soft delete (recycle bin + 93-day deleted-container collection); full Microsoft Purview list (DLP, retention, sensitivity labels, eDiscovery); Microsoft Graph for all operations.
• Agent readiness: right-sized articles, Applies to: audience lines, <!-- agent: --> metadata blocks, and embedded/llms.txt registered as a docfx build resource so it publishes.
• Acrolinx/MSWS: sentence-case headings, active voice, sentences within length limits.

Validation

Measured against Pem's SPE-Awareness eval (4 scenarios / 33 assertions; gpt-5.4 candidate, gpt-5.5 judge, pass ≥75%):

Scenario	Live baseline	This PR
Create App	~64–79%	100%
Enable Collaboration	~26–33%	~98–100%
Power Agent	~33–37%	~98%
Manage Content	~27–42%	~98%
Overall	~44%	~98%
Scenarios passed	0–1 / 4	4 / 4

[learn-build-service-prod]

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]

Learn Build status updates of commit 73aa5de:

⚠️ 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.

[ShreyasSar26]

Closing in favor of #10990, which now consolidates all awareness-docs changes plus the container-type refinements and full review-feedback resolution. #10990 is active (ready for review).

[learn-build-service-prod]

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]

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.