SPE agent ready docs -draft 1

docs/embedded/spe-docs-agent-ready/README.md

@@ -0,0 +1,45 @@
+# SharePoint Embedded — agent-ready documentation set
+
+This folder is a **proposed, drop-in agent-ready revamp** of the public SharePoint Embedded (SPE)
+documentation under `learn.microsoft.com/sharepoint/dev/embedded/**`. Every page is rewritten so an
+AI agent (Claude Code, ChatGPT, Copilot, Cursor, etc.) can read it and execute the next step without
+human-only affordances (no "click here", no screenshots, no buried GUIDs).
+
+It is structured to be uploaded as a single folder into a GitHub docs repo (e.g. `sp-dev-docs`),
+mirroring the live Learn folder layout.
+
+## What governs these pages
+
+| File | Role |
+|---|---|
+| `index.md` | Persona-tagged routing landing page + machine-readable navigation manifest. The canonical **structure** model. |
+| `_TEMPLATE-AND-RULES.md` | Per-page authoring spec (frontmatter shape, body templates by `task_type`, hard rules). |
+| `api-surface.json` | Every Microsoft Graph operation referenced by SPE docs (method, path, permissions, stability) + known API gaps. |
+| `toc.yml` | Table of contents for the set. |
+
+Each page carries an `agent:` frontmatter block, a `<!-- PROPOSED ... -->` status banner, stable
+section anchors, typed inputs/outputs, explicit failure modes, Verify and Troubleshooting sections,
+and `manual:` blocks for any unavoidable portal/PowerShell step.
+
+## Page inventory
+
+Pages mirror the live Learn paths called out in the `index.md` navigation manifest:
+
+- `overview.md`, `scenarios-and-use-cases.md`, `whats-new.md`
+- `getting-started/` — `spembedded-for-vscode`, `containertypes`, `register-api-documentation`
+- `development/` — `app-architecture`, `auth`, `sharing-and-perm`, `limits-calling`, `fluid`
+- `development/declarative-agent/` — `sharepoint-embedded-knowledge-source`
+- `development/content-experiences/` — `office-experience`, `user-experiences-overview`, `search-content`
+- `development/tutorials/` — `launch-experience`, `metadata`, `using-file-preview`, `doc-processing-acs`, `using-webhooks`, `migrate-abs-to-spe`, `vendor-install-app-customer`
+- `administration/billing/` — `billing`, `billingmanagement`, `meters`
+- `administration/developer-admin/` — `dev-admin`
+- `administration/` — `adminrole`
+- `administration/consuming-tenant-admin/` — `cta`, `ctapowershell`, `ctaux`
+- `compliance/` — `security-and-compliance`
+
+## Status
+
+All pages are marked `last_validated: proposed`. Validate every endpoint against `api-surface.json`
+and run an end-to-end harness before publishing.
+
+Author: Shreyas Saravanan

docs/embedded/spe-docs-agent-ready/_TEMPLATE-AND-RULES.md

@@ -0,0 +1,172 @@
+# Agent-Ready Page Template & Rules (authoring spec for the revamped SPE docs)
+
+> Every `.md` file under `revamped-docs/` MUST follow this spec. It operationalizes
+> `spe-agent-ready-standards.md` (v0.1) and the per-page requirements in
+> `spe-per-document-changes.md`. Use real Graph endpoints from `api-surface.json`.
+> These are PROPOSED drop-in replacements for `sp-dev-docs/docs/embedded/**`.
+
+## 0. Status banner (top of every page body, after frontmatter)
+Add this HTML comment as the first line of the body:
+`<!-- PROPOSED agent-ready revamp · draft · validate against api-surface.json before publishing -->`
+
+## 1. Frontmatter (every page)
+Preserve realistic Learn frontmatter, then add the `agent:` block.
+
+```yaml
+---
+title: <Sentence case, outcome-oriented>
+description: <one sentence, <=160 chars>
+ms.topic: <article | how-to | quickstart | reference | concept-article>
+ms.service: sharepoint-online
+ms.author: vesaj
+author: VesaJuvonen
+ms.date: 06/16/2026
+ms.localizationpriority: high
+agent:
+  schema_version: 1
+  task_type: <concept | quickstart | how-to | reference>
+  outcome: <one observable post-condition, third person>   # how-to/quickstart only
+  estimated_minutes: <int>                                  # how-to/quickstart only
+  difficulty: <beginner | intermediate | advanced>
+  roles: [<app-developer | enterprise-developer | consuming-admin | owning-admin | m365-admin | compliance-officer | end-user | migration-engineer>]
+  prerequisites:
+    - uri: /sharepoint/dev/embedded/<path>
+      kind: <concept | how-to>
+    - capability: <entra-app-admin | spe-admin | global-admin | m365-subscription | azure-subscription | container-type-owner | payg-billing-configured>
+  api_surface:                  # every endpoint this page tells the reader to call; omit if none
+    - id: <id from api-surface.json>
+      method: POST
+      path: /storage/fileStorage/containers
+      permissions: [FileStorageContainer.Selected]
+  inputs:                       # every {placeholder} used in code; omit if none
+    - name: container-id
+      type: uuid
+      source: <prior-step | user-supplied | app-registration | entra-portal | generated>
+  outputs:                      # observable success criteria; omit if none
+    - name: container-id
+      type: uuid
+      verify: GET /storage/fileStorage/containers/{container-id} returns 200
+  next_steps:
+    - uri: /sharepoint/dev/embedded/<path>
+      when: <always | multi-tenant-app | needs-search | migrating-from-azure-blob>
+  related:
+    - uri: /sharepoint/dev/embedded/<path>
+  stability: <ga | beta | preview | deprecated>
+  last_validated: proposed      # literal string "proposed" until an end-to-end harness run stamps a date
+---
+```
+
+## 2. Body templates by task_type
+
+### how-to / quickstart (REQUIRED section order)
+```
+# {Title}
+<!-- PROPOSED ... -->
+
+{One short paragraph: what the reader will have at the end. No marketing.}
+
+## Prerequisites
+- [<page>](/sharepoint/dev/embedded/<path>) — <why>
+- Capability: <capability> (e.g., an Entra app with Application Administrator role)
+
+## Inputs
+| Placeholder | Type | Where it comes from |
+|---|---|---|
+| `{container-id}` | uuid | A prior step / user-supplied |
+
+## Steps
+
+### Step 1 — {Imperative verb phrase, one outcome} {#step-1}
+{One sentence of why, then the action.}
+
+```http
+POST https://graph.microsoft.com/v1.0/storage/fileStorage/containers
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{ "displayName": "{display-name}", "containerTypeId": "{container-type-id}" }
+```
+
+**Expected response:** `201 Created` with a `fileStorageContainer` whose `status` is `inactive`.
+
+**On failure:**
+- `403 Forbidden` (`accessDenied`) → admin consent not granted. See [Grant ... permissions](...).
+- `400 Bad Request` → `containerTypeId` not registered on this tenant.
+
+### Step 2 — ... {#step-2}
+...
+
+## Verify
+```http
+GET https://graph.microsoft.com/v1.0/storage/fileStorage/containers/{container-id}
+```
+Returns `200 OK` with `status` equal to `active`.
+
+## Troubleshooting
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `401 Unauthorized` | Token missing/expired or wrong scope | Re-acquire a token with the permission in **Inputs** |
+| `403 Forbidden` | Admin consent not granted | Grant consent, then re-acquire the token |
+| `429 Too Many Requests` | Throttled | Honor `Retry-After`; back off exponentially. See [Limits](/sharepoint/dev/embedded/development/limits-calling) |
+
+## Next steps
+- [<page>](/sharepoint/dev/embedded/<path>)
+
+## Related
+- [<page>](/sharepoint/dev/embedded/<path>)
+```
+
+### concept (REQUIRED section order)
+```
+# {Title}
+<!-- PROPOSED ... -->
+
+## What it is
+## Why it matters / when to use
+## When NOT to use
+## Key terms
+## How it fits together   (owning vs consuming tenant, content vs control plane, where relevant)
+## Related
+```
+Concept pages MUST NOT contain imperative steps or API call instructions — link to the how-to instead.
+
+### reference (REQUIRED section order)
+```
+# {Title}
+<!-- PROPOSED ... -->
+
+## <Schema / table of values / limits / cmdlets>   (structured tables only)
+## Examples
+## See also
+```
+
+## 3. Hard rules (enforced; CI would block on these)
+- Every fenced code block declares a language: `http`, `bash`, `pwsh`, `json`, `yaml`, `csharp`, `typescript`, `python`. No bare ```` ``` ````.
+- Every `{placeholder}` in a code block is kebab-case and declared in `agent.inputs`. Never `{your-client-id}`, never `<your value here>`.
+- Every how-to/quickstart step ends in a real call (```http``` / ```bash``` / ```pwsh```) or a `manual:` block; declares an expected status; and lists ≥1 named failure mode.
+- A portal/PowerShell-only action uses a `manual:` block carrying `ui_path` + `api_equivalent` (or `api_equivalent: none — see api-surface.json gap <id>` if no API exists) + a `verify`.
+- Callouts use `> [!NOTE]` / `> [!IMPORTANT]` / `> [!WARNING]`. No bare **Note:** lines.
+- BANNED in step bodies (outside `manual:`): "click", "tap", "press", "navigate to" (without a URL), "see the screenshot", "as shown above/below", "simply", "just", "easily", "should be familiar with", "in a previous step" (use `{#step-n}` anchors).
+- Section anchors are stable: `{#step-1}`, `{#verify}`, `{#troubleshooting}`.
+- Permission GUIDs / endpoint metadata go in JSON or tables, never prose bullets.
+- For any endpoint, pull method/path/permissions/stability from `api-surface.json`. If it's `beta`, say so and mark `stability: beta`. If it's a `gaps[]` entry, document the manual path AND reference the gap id.
+
+## 4. `manual:` block shape (for unavoidable portal/PowerShell steps)
+```yaml
+manual:
+  description: Activate pay-as-you-go billing for SharePoint Embedded.
+  ui_path: Microsoft 365 admin center → Setup → Pay-as-you-go services → SharePoint Embedded
+  api_equivalent: none — no Graph API today; see api-surface.json gap "activateConsumingTenantPayg"
+  verify:
+    method: GET
+    path: /storage/fileStorage/containerTypes/{container-type-id}
+```
+
+## 5. File naming & placement
+- Use the path given in your assignment, under `revamped-docs/`, mirroring Learn folders.
+- One outcome per file. Split pages get separate files as named.
+- Lowercase kebab-case filenames.
+
+## 6. Tone
+Second-person imperative for steps; third-person declarative for concepts. Present tense. Quantify or omit ("up to 25 container types per tenant", not "many").
+```

docs/embedded/spe-docs-agent-ready/administration/adminrole.md

@@ -0,0 +1,108 @@
+---
+title: SharePoint Embedded Administrator role
+description: What the SharePoint Embedded Administrator role grants, how it differs from a SharePoint admin, and the tasks it enables in developer and consuming tenants.
+ms.topic: concept-article
+ms.service: sharepoint-online
+ms.author: ShreyasSar26
+author: ShreyasSaravanan
+ms.date: 06/16/2026
+ms.localizationpriority: high
+agent:
+  schema_version: 1
+  task_type: concept
+  difficulty: beginner
+  roles: [owning-admin, consuming-admin, m365-admin]
+  prerequisites:
+    - uri: /sharepoint/dev/embedded/overview
+      kind: concept
+    - capability: global-admin
+  api_surface: []
+  next_steps:
+    - uri: /sharepoint/dev/embedded/administration/developer-admin/dev-admin
+      when: always
+    - uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/cta
+      when: admin-consuming-tenant
+  related:
+    - uri: /sharepoint/dev/embedded/administration/developer-admin/dev-admin
+    - uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/cta
+    - uri: /sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell
+  stability: ga
+  last_validated: proposed
+---
+
+# SharePoint Embedded Administrator role
+<!-- PROPOSED agent-ready revamp · draft · validate against api-surface.json before publishing -->
+
+## What it is
+
+The **SharePoint Embedded Administrator** is a dedicated Microsoft Entra / Microsoft 365 role for managing SharePoint Embedded container types and containers through [SharePoint PowerShell](https://learn.microsoft.com/powershell/module/sharepoint-online/connect-sposervice) and the SharePoint admin center. The role is required for [developer admins](/sharepoint/dev/embedded/administration/developer-admin/dev-admin) to create container types through PowerShell cmdlets, and for consuming tenant admins to manage containers created in their tenants.
+
+The role is available in both **Microsoft Entra** and the **Microsoft 365 admin center**. The **Global Administrator** role already has all the permissions of the SharePoint Embedded Administrator role; a Global Administrator can assign the role to a user so that user can act as a developer admin or a consuming tenant admin for SharePoint Embedded.
+
+> [!IMPORTANT]
+> The SharePoint Embedded Administrator role does **not** have access to site management. A holder can't see the **Active sites** or **Deleted sites** pages in the SharePoint admin center and can't run site-specific PowerShell cmdlets. The role is scoped to SharePoint Embedded container types and containers only.
+
+## Why it matters / when to use
+
+Assign this role to grant SharePoint Embedded administration without granting full SharePoint or tenant administration.
+
+- Assign it to a **developer admin** who needs to create and manage container types and billing in the developer (owning) tenant.
+- Assign it to a **consuming tenant admin** who needs to manage the containers created in their tenant.
+- Prefer it over Global Administrator for least-privilege: it covers SharePoint Embedded tasks without the broad surface of Global Administrator and without SharePoint site management.
+
+## When NOT to use
+
+- Do not assign it when the user needs to manage SharePoint **sites** (active/deleted sites, site-specific cmdlets); it has no site-management access. Use a SharePoint or Global admin role for that.
+- Do not assign a separate SharePoint Embedded Administrator role to an existing **Global Administrator**; that role already includes all SharePoint Embedded Administrator permissions.
+- Do not rely on this role for Azure billing setup. Attaching a billing profile requires owner or contributor permissions on an **Azure subscription**, which is a separate authorization. See [Developer admin](/sharepoint/dev/embedded/administration/developer-admin/dev-admin#roles-and-permissions).
+
+## Key terms
+
+| Term | Meaning |
+|---|---|
+| SharePoint Embedded Administrator | Dedicated Entra / Microsoft 365 role for SharePoint Embedded container type and container management; no site-management access. |
+| Global Administrator | Tenant-wide admin role that already includes all SharePoint Embedded Administrator permissions and can assign the role. |
+| Developer (owning) tenant | The tenant where container types are created and standard billing is configured. |
+| Consuming tenant | The tenant where a registered application's containers are created and managed. |
+| Developer admin | A SharePoint Embedded Administrator (or Global Administrator) acting in the developer tenant. |
+| Consuming tenant admin | A SharePoint Embedded Administrator (or Global/SharePoint Administrator) acting in a consuming tenant. |
+
+## How it fits together
+
+The same role label applies in two contexts, with different supported tasks depending on which tenant the holder operates in.
+
+### Tasks in the developer (owning) tenant
+
+A SharePoint Embedded Administrator in the developer tenant can, through PowerShell:
+
+- Create container types:
+  - Standard container type with standard billing.
+  - Standard container type with direct-to-customer (passthrough) billing.
+  - Trial container type.
+- Manage container types:
+  - View container types in the developer tenant.
+  - Edit properties of a container type.
+  - Set configuration properties of a container type.
+  - Manage billing of applications / container types for standard billing.
+
+For the cmdlets, see [Developer admin](/sharepoint/dev/embedded/administration/developer-admin/dev-admin).
+
+### Tasks in the consuming tenant
+
+A SharePoint Embedded Administrator in a consuming tenant can, through PowerShell, perform application administration (get details of all SharePoint Embedded applications, get a specific application, get permissions of owning applications, configure external sharing of a container) and container administration (get details of all containers — including sorted by storage and archived — get a specific container, set the sensitivity label of a container, soft-delete a container, list soft-deleted containers, restore a soft-deleted container, and permanently delete a soft-deleted container).
+
+Through the SharePoint admin center, the same role can view the Active, Archived, and Deleted container pages and a container's details, and can archive an active container, reactivate an archived container, soft-delete a container, restore a deleted container, and purge a deleted container.
+
+For the consuming-tenant cmdlets and UX, see [Consuming tenant admin overview](/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta) and [Container management in PowerShell](/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell).
+
+### Assigning the role
+
+A Global Administrator assigns the SharePoint Embedded Administrator role through either Microsoft Entra or the Microsoft 365 admin center. For the step-by-step assignment procedure, see [Developer admin — Assign the SharePoint Embedded Administrator role](/sharepoint/dev/embedded/administration/developer-admin/dev-admin#step-1).
+
+## Related
+
+- [Developer admin](/sharepoint/dev/embedded/administration/developer-admin/dev-admin)
+- [Consuming tenant admin overview](/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta)
+- [Container management in PowerShell](/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell)
+- [Pay-as-you-go billing](/sharepoint/dev/embedded/administration/billing/billing)
+- [Connect-SPOService](https://learn.microsoft.com/powershell/module/sharepoint-online/connect-sposervice)