Enhance AI Web API integration validation and documentation

- Updated `validate-ai-webapi.js` to enforce OData version headers and Content-Type for Search Summary calls.
- Added warnings for potential issues with disabled-state envelopes and plain-scalar prompt values.
- Improved YAML parsing for site settings to handle block-literal and folded-scalar formats.
- Documented caller-suppress mode in `create-webroles/SKILL.md` to streamline deployment prompts.
- Clarified decision framework for backend integration in `decision-framework.md`, addressing field-list drift.
- Revised `SKILL.md` for `/integrate-webapi` to defer git commits and suppress deploy prompts in AI-only read mode.
- Introduced new prompt templates for agent invocation and exploration in `add-ai-webapi` references.
- Added structured follow-up questions for scope confirmation and list-trigger choices in `scope-classification.md`.

Author: neerajnandwana

plugins/power-pages/agents/ai-webapi-integration.md

@@ -32,17 +32,21 @@ tools:
 # AI Summarization Web API Integration Agent
 
 You are a Power Pages generative-AI summarization integration specialist. You implement production
-code for one or more of the three summarization endpoints, following the same shape as the
+code for one or both of the two summarization endpoints — **Search Summary**
+(`/_api/search/v1.0/summary`) and **Data Summarization**
+(`/_api/summarization/data/v1.0/<entitySet>(<id>)?...`) — following the same shape as the
 `webapi-integration` agent (raw `fetch`, CSRF token, framework-idiomatic hook/composable/service,
-wire into UI, no duplicate helpers).
+wire into UI, no duplicate helpers). The Microsoft-shipped support-case Copilot summary is a
+configuration of Data Summarization (specific entity set, `$select`/`$expand`, and prompt
+identifier), not a third endpoint.
 
 ## Reference docs
 
 Read these first — they have the authoritative API shapes, headers, request bodies, and error
 codes:
 
 - `${CLAUDE_PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md` — canonical reference
-  for all three APIs with the CSRF rules
+  for both APIs (Search Summary, Data Summarization) with the CSRF rules
 - `${CLAUDE_PLUGIN_ROOT}/agents/webapi-integration.md` — general Web API integration patterns
   (framework detection, file placement, hook conventions)
 
@@ -62,9 +66,9 @@ Upstream Microsoft Learn sources (already captured in the reference above — on
 - **Reuse `getCsrfToken`** — if an existing helper is present (from `/add-cloud-flow`, a prior
   `/add-ai-webapi` run, or any custom code), import and reuse it. Only create it if nothing
   suitable exists.
-- **One service file for all three APIs** — group `fetchSearchSummary`, `fetchDataSummary`, and
-  `fetchCaseSummary` in a single service (e.g. `src/services/aiSummaryService.ts`). Do not create
-  one file per endpoint.
+- **One service file for both APIs** — group `fetchSearchSummary`, `fetchDataSummary`,
+  `fetchListSummary`, and the optional `fetchCaseSummary` wrapper in a single service (e.g.
+  `src/services/aiSummaryService.ts`). Do not create one file per endpoint.
 - **CSRF token is mandatory; X-Requested-With is recommended.** Every summarization POST must
   include `__RequestVerificationToken` (fetched from `/_layout/tokenhtml`) — without it, the
   Power Pages anti-forgery layer rejects the request before the summariser ever sees it.
@@ -659,26 +663,28 @@ below.
 - **Data summarization on a support-case detail page (when the caller specified the
   Microsoft-shipped support-case scenario)** → find the case/incident detail page (look for
   components that read a case `id` from the URL, or match names like `Case*`, `Incident*`,
-  `Ticket*`). Add a collapsible summary section at the top that mirrors the Microsoft-shipped
-  Copilot summary card. Reproduce all the affordances from the MS Learn case-page template — not
-  just the chevron:
-
-  | Element | Purpose | Source |
-  |---------|---------|--------|
-  | Gradient border | Visual marker that this is AI output (blue → cyan → purple) | `border-image: linear-gradient(90deg, rgb(70,79,235) 35%, rgb(71,207,250) 70%, rgb(180,124,248) 92%) 1` |
-  | Sparkle icon + "Summary" label | Header of the section | MS Learn SVG (paths omitted here — copy verbatim from the case-page article) |
-  | Chevron (rotates on toggle) | Collapses/expands the summary | `.chevron` with `transform: rotate(45deg)` / `rotate(-135deg)` |
-  | Shimmer block | Loading state while the request is in flight | `.shimmer` keyframes from MS Learn |
-  | Summary text | Output of `response.Summary` | Service call result |
-  | Copy button (page icon) | One-click copy of the summary to clipboard (`navigator.clipboard.writeText`) | MS Learn SVG |
-  | Thumbs-up + thumbs-down | User feedback buttons (wire to telemetry or leave as placeholder) | MS Learn SVGs |
-  | "AI-generated content may be incorrect" | Disclaimer alongside the feedback buttons | MS Learn text |
-
-  Keep the gradient border exact — it's the Copilot brand cue. Copy the two feedback SVGs and the
-  copy-button SVG directly from the MS Learn article's `<svg>` definitions so the section renders
-  identical to first-party Power Pages pages. The feedback click handlers can be no-ops (or wire
-  to `console.log` / a project-local analytics hook) — the important thing is the UI presence, so
-  users see the same affordances they would on a Microsoft-shipped portal template.
+  `Ticket*`). Add a collapsible summary section at the top that uses the **Copilot card visual
+  language** so the surface reads as AI output. The card shape is what matters — concrete
+  styling can adapt to the site's design system. Required affordances:
+
+  | Element | Purpose | Notes |
+  |---------|---------|-------|
+  | Gradient/accent border or background | Visual marker that this is AI output | The MS Learn case-page article uses `border-image: linear-gradient(90deg, rgb(70,79,235) 35%, rgb(71,207,250) 70%, rgb(180,124,248) 92%) 1`. Use that verbatim if the site has no design system; otherwise pick an equivalent accent that reads as Copilot/AI in this site's palette. |
+  | Sparkle icon + "Summary" label | Header of the section | The MS Learn SVG is the safe default; the site's icon library can replace it with an equivalent AI/sparkle glyph. |
+  | Chevron (rotates on toggle) | Collapses/expands the summary | Any rotating-chevron pattern is fine. |
+  | Loading state | Shimmer block (or the site's standard loading affordance) | Don't leave the slot empty during the request. |
+  | Summary text | Output of `response.Summary` | Run through the safe-markdown renderer for tabular-insight prompts. |
+  | Copy button | One-click copy to clipboard via `navigator.clipboard.writeText` | Standard icon button. |
+  | Thumbs-up + thumbs-down | User feedback affordance (handlers may be no-ops or wire to a project-local analytics hook) | Presence matters more than wiring — leaves room for telemetry later without redesign. |
+  | "AI-generated content may be incorrect" disclaimer | Required text alongside the feedback buttons | Use this exact wording. |
+
+  **Defaults vs. customisation.** When the site has no design system in place, copy the
+  MS Learn case-page CSS and SVGs verbatim — they ship working Copilot-grade output and
+  match what the user expects from first-party Power Pages templates. When the site does
+  have a design system (custom theme, tokens, icon set), match its conventions and use a
+  Copilot-equivalent accent — what matters is that users recognise the card as AI output,
+  not that every pixel matches Microsoft's reference. Do NOT skip any of the affordances
+  above; the row of affordances is the contract.
 - **Generic data summarization (single record)** → find the detail page for the target table and
   add a summary section next to the main content.
 - **List summary (collection)** → find the list / history / results page for the target table
@@ -915,9 +921,44 @@ the summarization service to import it.
 
 ---
 
+## Return value (contract with the orchestrator)
+
+When you complete (or fail and unwind), return a structured summary so the calling
+orchestrator can stage commits, present a final summary, and detect partial work. The
+orchestrator's Phase 5.5 explicitly relies on this list to do per-file `git add` instead of
+a broad `git add -A`.
+
+```text
+Files touched:
+  - <project-relative path>  [created | modified | replaced-marker]
+  - ...
+
+Markers consumed:
+  - <project-relative path>:<line>  kind=<search-summary | data-summarization>
+  - ...   (omit this section when no markers were involved)
+
+Reused infrastructure:
+  - getCsrfToken: <"defined inline" | "imported from <path>">
+  - aiSummaryService: <"created at <path>" | "extended at <path>">
+  - powerPagesApi.ts: <"present" | "absent">
+
+Follow-ups:
+  - <any post-Phase-5 work the orchestrator should know about — e.g. "ContentSizeLimit
+    setting still needs to be created in Phase 6 for the WorkOrderList list-summary target">
+```
+
+`replaced-marker` means the file already had a `POWERPAGES:AI-SLOT` comment and you both
+inserted the generated UI at the marker line and deleted the comment in the same edit.
+`modified` means an existing file was updated (e.g., extending an existing
+`aiSummaryService.ts` with another exported function); `created` means the file did not
+exist before this invocation.
+
+Do not return a long prose narrative — the orchestrator parses this list. Keep paths
+project-relative (relative to the project root containing `powerpages.config.json`).
+
 ## Key rules
 
-1. **Raw `fetch` for all three APIs** — never `powerPagesFetch` or `HttpClient` wrappers that inject
+1. **Raw `fetch` for both APIs** — never `powerPagesFetch` or `HttpClient` wrappers that inject
    OData-specific headers.
 2. **CSRF token is mandatory; X-Requested-With is recommended.** Always set
    `__RequestVerificationToken` (omitting it triggers anti-forgery rejection). Always set

plugins/power-pages/agents/ai-webapi-settings-architect.md

@@ -278,9 +278,16 @@ Prompt selection depends on the URL form captured in 3.2:
 
 ## Step 4: Cross-Check Web API Prerequisites
 
-For every table that will be summarised via the data summarization API (primary table **and** every
-`$expand` target), verify both `Webapi/<table>/enabled` and `Webapi/<table>/fields` exist in
-`.powerpages-site/site-settings/`.
+**Skip this step entirely when the only summarisation calls in the site are to
+`/_api/search/v1.0/summary`.** Search Summary has no per-table prereqs (no `Webapi/<table>/*`,
+no table permissions tied to a specific Dataverse table) — its enablement lives in the
+Copilot workspace toggle. If Step 3.1 found Search Summary calls AND Step 3.2 found **no**
+Data Summarization calls, jump to Step 5; the prerequisite block below would over-block a
+legitimate search-only run.
+
+Otherwise, for every table that will be summarised via the data summarization API (primary
+table **and** every `$expand` target), verify both `Webapi/<table>/enabled` and
+`Webapi/<table>/fields` exist in `.powerpages-site/site-settings/`.
 
 - **If the Web API site settings already exist**: include them in the plan as `✓ Prerequisite met`.
 - **If the Web API site settings are missing**: include a blocker in the plan that asks the user

plugins/power-pages/scripts/tests/validate-ai-webapi.test.js

@@ -393,3 +393,189 @@ test('project with no Summarization/prompt settings does not warn', (t) => {
   assert.equal(result.status, 0, result.stderr);
   assert.doesNotMatch(result.stderr, /Summarization-prompt/);
 });
+
+// --- OData 4.0 header checks (data summarization) ---
+
+test('data summarization missing OData-MaxVersion header is blocked', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(
+    projectRoot,
+    'src/services/aiSummaryService.ts',
+    VALID_DATA_SERVICE.replace("'OData-MaxVersion': '4.0',", '')
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing OData-MaxVersion: 4\.0/);
+});
+
+test('data summarization missing OData-Version header is blocked', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(
+    projectRoot,
+    'src/services/aiSummaryService.ts',
+    VALID_DATA_SERVICE.replace("'OData-Version': '4.0',", '')
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing OData-Version: 4\.0/);
+});
+
+test('search-only project does not require OData headers', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_SEARCH_SERVICE);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /OData-/);
+});
+
+// --- Search Summary content-type check ---
+
+test('Search Summary with application/json instead of urlencoded is blocked', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(
+    projectRoot,
+    'src/services/aiSummaryService.ts',
+    VALID_SEARCH_SERVICE.replace(
+      "'Content-Type': 'application/x-www-form-urlencoded',",
+      "'Content-Type': 'application/json',"
+    )
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /missing Content-Type: application\/x-www-form-urlencoded/);
+});
+
+// --- Disabled-state envelope advisory ---
+
+test('Search Summary without SearchSummaryApiError is warned but not blocked', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_SEARCH_SERVICE);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stderr, /SearchSummaryApiError/);
+});
+
+test('Search Summary with SearchSummaryApiError export does not warn about envelope', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(
+    projectRoot,
+    'src/services/aiSummaryService.ts',
+    VALID_SEARCH_SERVICE +
+      '\nexport class SearchSummaryApiError extends Error {}\nexport function isGenAiSearchDisabled() { return false; }\n'
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /SearchSummaryApiError/);
+});
+
+test('Search Summary with inline body.Code === pattern does not warn about envelope', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_SEARCH_SERVICE);
+  writeProjectFile(
+    projectRoot,
+    'src/components/SearchSummaryCard.tsx',
+    "export function detect(body) { return body.Code === 400 && body.Message !== ''; }"
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /SearchSummaryApiError/);
+});
+
+test('Data-only project does not warn about disabled-state envelope', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_DATA_SERVICE);
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /SearchSummaryApiError/);
+});
+
+// --- Plain-scalar long prompt advisory ---
+
+test('plain-scalar prompt over 200 chars warns about block-literal', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_DATA_SERVICE);
+  const longPrompt = 'X'.repeat(300);
+  writeProjectFile(
+    projectRoot,
+    '.powerpages-site/site-settings/Summarization-prompt-plain_long.sitesetting.yml',
+    `id: 44444444-4444-4444-8444-444444444444\nname: Summarization/prompt/plain_long\nvalue: ${longPrompt}\n`
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stderr, /Summarization-prompt-plain_long\.sitesetting\.yml: prompt value is 300 characters and uses plain-scalar YAML/);
+});
+
+test('block-literal prompt over 200 chars does not warn about plain-scalar', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_DATA_SERVICE);
+  writeProjectFile(
+    projectRoot,
+    '.powerpages-site/site-settings/Summarization-prompt-block_long.sitesetting.yml',
+    promptSettingYaml('Y'.repeat(300))
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /uses plain-scalar YAML/);
+});
+
+test('plain-scalar prompt under 200 chars does not warn about plain-scalar', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_DATA_SERVICE);
+  writeProjectFile(
+    projectRoot,
+    '.powerpages-site/site-settings/Summarization-prompt-short_plain.sitesetting.yml',
+    "id: 55555555-5555-4555-8555-555555555555\nname: Summarization/prompt/short_plain\nvalue: Summarize key details and critical information\n"
+  );
+
+  const result = runValidator(projectRoot);
+  assert.equal(result.status, 0, result.stderr);
+  assert.doesNotMatch(result.stderr, /uses plain-scalar YAML/);
+});
+
+// --- Folded scalar (`>`) parsing ---
+
+test('folded-scalar prompt is parsed and size-checked', (t) => {
+  const projectRoot = createTempProject(t);
+  writeProjectFile(projectRoot, 'powerpages.config.json', '{}');
+  writeProjectFile(projectRoot, 'src/services/aiSummaryService.ts', VALID_DATA_SERVICE);
+  // Build a folded-scalar YAML file by hand. Folded scalars use `>`; the validator
+  // should pick up the indented body (size-check it) instead of treating it as null.
+  const longBody = 'Z'.repeat(2200);
+  const yaml = [
+    'id: 66666666-6666-4666-8666-666666666666',
+    'name: Summarization/prompt/folded_one',
+    'value: >',
+    '  ' + longBody,
+    '',
+  ].join('\n');
+  writeProjectFile(
+    projectRoot,
+    '.powerpages-site/site-settings/Summarization-prompt-folded_one.sitesetting.yml',
+    yaml
+  );
+
+  const result = runValidator(projectRoot);
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Summarization-prompt-folded_one\.sitesetting\.yml: prompt value is \d+ characters, exceeding the supported maximum of 2000/);
+});