Add AI Web API (summarization) integration skill for Power Pages

Adds the add-ai-webapi skill: Search Summary and Data Summarization
integration for Power Pages code sites, with supporting agents, references,
evals, and a PostToolUse validator. Routed from integrate-backend.

Validator (validate-ai-webapi.js) highlights:
- Header/$select/OData/content-type checks are project-wide (a token present
  anywhere under src/ satisfies them), so integrations that centralize header
  and URL construction in a shared helper are not false-failed.
- Citation-parser detection matches the escaped-bracket regex form the skill
  ships (/\[\[(\d+)\]\]\(/) plus a literal [[N]]( token fallback.
- CSRF rationale clarified: token is required on these POST requests
  regardless of mutation semantics; the endpoints are read-only.
- Prompt-length error notes the request body accepts no prompt text
  (only InstructionIdentifier / RecommendationConfig).

This commit collapses the prior branch history (which had been doubled by a
bad self-merge) into a single clean change rebased onto current main, and
adopts main's dynamic TRACKED_SKILLS discovery (add-ai-webapi is auto-tracked).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: neerajnandwana

evals/power-pages/add-ai-webapi/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "add-ai-webapi",
+  "notes": "Dry-run decision-trace evals: each prompt asks the subagent to analyse a Power Pages fixture project using the skill and output the decisions it would make (integration manifest, Phase 5 agent-invocation prompts, Phase 6 settings plan). Sub-skill/agent invocations are mocked — the subagent prints what it would send without actually spawning agents. This isolates the skill's classification and routing logic from the broader Power Pages environment.",
+  "evals": [
+    {
+      "id": 1,
+      "name": "list-only-workorders",
+      "prompt": "You have read access to a Power Pages Single Page Application (SPA) site fixture at <FIXTURE_PATH>. The site has a WorkOrderList.tsx page that fetches and iterates over a collection of cr363_workorder records (it's a list page). The user has just invoked the /add-ai-webapi skill on this project and wants to add an AI summary to this list page.\n\nLoad the skill from <SKILL_PATH>. Execute Phases 1-3 (site check, explore, plan review) and draft what Phase 5 and Phase 6 WOULD do — but DO NOT actually invoke any sub-skills, sub-agents, or run any scripts. Instead, produce a single output file at <OUTPUT_PATH>/decision-trace.md containing:\n\n1. ## Phase 2 integration manifest — the compiled manifest table, one row per target, with the new Target kind column.\n2. ## Phase 3 AskUserQuestion prompts — the exact question(s) you would ask the user (integration selection + per-target follow-ups), with the full option list per question.\n3. ## Phase 5 agent-invocation prompt — for every data/case target, the exact prompt string you would send to the ai-webapi-integration agent, with all placeholders filled in.\n4. ## Phase 6 settings-architect invocation — the exact prompt string you would send to the ai-webapi-settings-architect agent.\n5. ## Projected settings plan — the settings the architect would propose (name + value + write-path script-or-manual for each), based on the prompt-pattern and URL-form rules in the architect's Step 3/5.\n\nFor any AskUserQuestion, assume the user picks the first/Recommended option. Do not actually modify any files in the fixture. Do not invoke Task, Skill, or Bash to run scripts.",
+      "files": [],
+      "fixture": "list-only-workorders"
+    },
+    {
+      "id": 2,
+      "name": "single-record-case-regression",
+      "prompt": "You have read access to a Power Pages Single Page Application (SPA) site fixture at <FIXTURE_PATH>. The site has a CaseDetail.tsx page that reads a case id from the URL querystring and displays a single incident record. The user has just invoked the /add-ai-webapi skill on this project and wants to add the canonical case-page Copilot preset.\n\nLoad the skill from <SKILL_PATH>. Execute Phases 1-3 and draft what Phase 5 and Phase 6 WOULD do — but DO NOT actually invoke any sub-skills, sub-agents, or run any scripts. Produce <OUTPUT_PATH>/decision-trace.md with the same 5 sections as eval 1.\n\nFor any AskUserQuestion, assume the user picks the first/Recommended option. Do not actually modify any files in the fixture. Do not invoke Task, Skill, or Bash to run scripts.",
+      "files": [],
+      "fixture": "single-record-case"
+    },
+    {
+      "id": 3,
+      "name": "collision-search-vs-list-results",
+      "prompt": "You have read access to a Power Pages Single Page Application (SPA) site fixture at <FIXTURE_PATH>. The site has TWO pages: SearchResults.tsx (a pure search-results page that calls /_api/search/v1.0/query) AND WorkOrderResults.tsx (which iterates over a collection of cr363_workorder records — despite the `Results` suffix, it's a Dataverse list). The user wants to add AI summaries to both pages.\n\nLoad the skill from <SKILL_PATH>. Execute Phases 1-3 and draft what Phase 5 and Phase 6 WOULD do — but DO NOT actually invoke any sub-skills, sub-agents, or run any scripts. Produce <OUTPUT_PATH>/decision-trace.md with the same 5 sections as eval 1.\n\nFor any AskUserQuestion, assume the user picks the first/Recommended option. Do not actually modify any files in the fixture. Do not invoke Task, Skill, or Bash to run scripts.",
+      "files": [],
+      "fixture": "collision-search-vs-results"
+    }
+  ]
+}

plugins/power-pages/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "power-pages",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Create and deploy Power Pages sites using modern development approaches. Supports code sites (SPAs) with React, Angular, Vue, or Astro. Includes ALM orchestration (plan-alm) with a solution-splitting decision tree, per-solution pipelines, Azure Blob asset advisory, manifest schema v2 for multi-solution deployments, and force-link remediation for cross-host pipeline migrations.",
   "author": {
     "name": "Microsoft",

plugins/power-pages/AGENTS.md

@@ -32,7 +32,10 @@ Read `PLUGIN_DEVELOPMENT_GUIDE.md` for UX and reliability standards when creatin
 agents/
   data-model-architect.md      ← Agent: proposes Dataverse data models (read-only)
   webapi-integration.md        ← Agent: implements Web API integration in frontend code
-  webapi-permissions.md        ← Agent: proposes Web API permissions plan (read-only)
+  table-permissions-architect.md ← Agent: proposes table permissions plan (read-only)
+  webapi-settings-architect.md ← Agent: proposes Web API site settings with validated column names (read-only)
+  ai-webapi-integration.md     ← Agent: implements generative-AI summarization service code + UI wiring
+  ai-webapi-settings-architect.md ← Agent: proposes Summarization/* site settings (read-only)
 scripts/
   generate-uuid.js             ← Shared UUID v4 generator (used by multiple skills)
   check-activation-status.js   ← Checks if site is already activated (used by deploy-site, activate-site)
@@ -76,6 +79,14 @@ skills/
   integrate-webapi/
     SKILL.md                   ← Web API integration skill definition
     scripts/validate-webapi-integration.js ← Node script validating Web API integration code
+  add-ai-webapi/
+    SKILL.md                   ← Generative-AI summarization integration skill (Layer 3; preview)
+    references/ai-api-reference.md ← Canonical Search/Data Summarization API shapes, headers, error codes
+    references/explore-prompt.md   ← Phase 2 Explore-agent prompt body + manifest shape
+    references/scope-classification.md ← Phase 3 list-trigger / scope-confirmation question mapping
+    references/agent-invocation-prompt.md ← Phase 5 ai-webapi-integration prompt template
+    references/framework-equivalents.md ← Vue/Angular/Astro safe-markdown + citation rendering snippets
+    scripts/validate-ai-webapi.js ← Node script validating summarization code, headers, and Summarization/* settings
   setup-auth/
     SKILL.md                   ← Authentication & authorization skill definition
     references/authentication-reference.md ← Login/logout flow, auth service, framework patterns
@@ -123,7 +134,10 @@ Auto-triggered by the main conversation when relevant:
 
 - `data-model-architect`: Read-only agent that analyzes site requirements, discovers existing Dataverse tables via OData API, and proposes a data model (new/modified/reused tables + Mermaid ER diagram). Uses `pac env who` + Azure CLI auth to query Dataverse. Renders the ER diagram visually in the browser via Playwright (writes a temp HTML file with Mermaid.js CDN, navigates to it, takes a screenshot) before entering plan mode. Does NOT create, modify, or delete any tables — purely advisory. The main conversation uses its output to create tables.
 - `webapi-integration`: Implementation agent that creates production-ready Web API integration code for a single Dataverse table in a Power Pages code site. Detects the frontend framework (React/Vue/Angular/Astro), creates a shared `powerPagesApi.ts` client (token management, retry logic, OData URL builder) if one doesn't exist, then generates TypeScript entity types, a domain mapper, and a CRUD service layer for the target table. Also creates framework-specific hooks (React), composables (Vue), or injectable services (Angular). Follows Power Pages Web API best practices: `/_api/` endpoints, dual token headers, `@odata.bind` for lookups, explicit `$select` (never `*`), formatted value annotations, exponential backoff retry, and 8-minute token TTL. Handles one table per invocation — invoke separately for multiple tables.
-- `webapi-permissions`: Read-only agent that analyzes site code, discovers existing web roles and table permissions, queries Dataverse for table columns, and proposes a complete Web API permissions plan (table permissions + site settings). Checks for `.powerpages-site` folder to verify site deployment. Renders a Mermaid flowchart showing web roles → table permissions → tables visually in the browser via Playwright. Never uses `*` for Web API field settings — always lists specific columns. Does NOT create any YAML files — purely advisory. The main conversation uses its output to create table permission and site setting files.
+- `table-permissions-architect`: Read-only agent that analyzes site code, discovers existing web roles and table permissions, and proposes a table-permissions plan (web roles → table permissions with CRUD flags and scopes) rendered as a Mermaid flowchart. Checks for `.powerpages-site` folder to verify site deployment. Presents the plan via plan mode; after approval, creates web role and table-permission YAML files using deterministic scripts. Supports an **AI-only read posture** (invoked transitively by `/add-ai-webapi` via `/integrate-webapi`) that proposes `read: true` only, with Parent scope + `appendTo` for `$expand` targets. Invoked by `/integrate-webapi` and `/audit-permissions`.
+- `webapi-settings-architect`: Read-only agent that queries Dataverse for exact column LogicalNames (case-sensitive) and proposes `Webapi/<table>/enabled` and `Webapi/<table>/fields` site settings. Never uses `*` for field settings except for aggregate OData queries — always lists specific columns. Presents the plan via plan mode; after approval, creates site-setting YAML files using `create-site-setting.js`. Supports the **AI-only read posture** (minimal fields list: no primary key, only `_<col>_value` lookup read forms). Invoked by `/integrate-webapi`.
+- `ai-webapi-integration`: Implementation agent that creates production-ready generative-AI summarization service code for a Power Pages SPA site — Search Summary (`/_api/search/v1.0/summary`) and Data Summarization (`/_api/summarization/data/v1.0/...`). Uses raw `fetch` (never the OData wrapper), attaches the `__RequestVerificationToken` CSRF header, groups all functions in a single `aiSummaryService.*` file, emits a framework-idiomatic wrapper (React hook / Vue composable / Angular service / Astro util), and wires real UI call sites with loading/error/content/empty branches, citation rendering, and a safe-markdown renderer. Invoked **sequentially per target** by `/add-ai-webapi` (every target shares the one service file, so parallel runs would conflict).
+- `ai-webapi-settings-architect`: Read-only agent that proposes the three Layer-3 summarization settings — `Summarization/Data/Enable`, per-prompt `Summarization/prompt/<identifier>`, and `Summarization/Data/ContentSizeLimit` (mandatory `200000` for list summaries). Cross-checks that Layer 1/2 prerequisites (`Webapi/<table>/*`, table permissions) exist for every summarised table and `$expand` target. Presents the plan via plan mode; after approval, creates site-setting YAMLs (script path, or hand-written block-literal YAML for long/complex prompts). Invoked by `/add-ai-webapi` Phase 6.
 
 ### Skills
 
@@ -136,7 +150,8 @@ User-invocable via `/power-pages:<skill-name>`:
 - `activate-site`: 5-step workflow — verify prerequisites (PAC CLI auth + Azure CLI token + cloud-aware API URL resolution + activation status check via shared script), gather parameters (site name, subdomain, website record ID), confirm with user, activate & poll via `skills/activate-site/scripts/activate-site.js`, present summary with site URL.
 - `add-seo`: 7-step workflow — verify site exists, gather SEO config (production URL, exclusions, meta description), plan & approve, create robots.txt, generate sitemap.xml from discovered routes, add meta tags (title, description, viewport, Open Graph, Twitter Card, favicon) to index.html, verify via Playwright & commit.
 - `create-webroles`: 6-step workflow — verify `.powerpages-site/web-roles/` exists (redirect to deploy-site if missing), discover existing roles, determine new roles needed, create web role YAML files with UUIDs from shared `scripts/generate-uuid.js`, verify web roles (validate files, UUIDs, uniqueness constraints), review & prompt deployment via deploy-site skill.
-- `integrate-webapi`: 7-step workflow — verify site exists, use Explore agent to analyze code and identify tables needing Web API integration, review plan with user, invoke `webapi-integration` agent per table to create API client/types/services/hooks, verify integrations (validate all files exist, project builds), invoke `webapi-permissions` agent to configure table permissions and site settings, review & deploy via `deploy-site` skill.
+- `integrate-webapi`: 7-step workflow — verify site exists, use Explore agent to analyze code and identify tables needing Web API integration, review plan with user, invoke `webapi-integration` agent per table to create API client/types/services/hooks, verify integrations (validate all files exist, project builds), invoke `table-permissions-architect` and `webapi-settings-architect` agents (in parallel) to configure table permissions and site settings, review & deploy via `deploy-site` skill. Supports an `[AI-READ-ONLY]` sentinel that hardens the flow to read-only when invoked by `/add-ai-webapi`.
+- `add-ai-webapi`: 8-phase workflow — verify site/deployment, Explore-agent scan for search/data summarization candidates, review plan with user, **delegate Layer 1/2** (Web API site settings + table permissions) to `/integrate-webapi` in AI-only read mode and to `/create-webroles`, invoke `ai-webapi-integration` agent **sequentially per target** to create the summarization service + framework wrapper + UI wiring, invoke `ai-webapi-settings-architect` for Layer 3 (`Summarization/*` settings), verify (header-contract grep, `$select` grep, build, validator), review & deploy. This skill owns **Layer 3 only** and delegates everything else. Validator: `skills/add-ai-webapi/scripts/validate-ai-webapi.js`. AI summarization APIs are a **preview** feature gated by a three-level admin hierarchy.
 - `setup-auth`: 8-step workflow — verify prerequisites (site deployed + web roles), gather auth requirements and plan, create auth service with Entra ID login/logout (anti-forgery token + form POST), create authorization utilities (role checking), create auth UI (AuthButton component), apply role-based access control to components, verify auth setup (validate files, build, auth UI renders), create `ProfileRedirectEnabled` site setting and deploy.
 - `setup-solution`: 7-step workflow — verify prerequisites, gather publisher/solution configuration (publisher prefix is irreversible — requires explicit confirmation), check existing publishers/solutions to avoid duplicates, create publisher + solution via OData API, add Power Pages website and web role components via `AddSolutionComponent`, verify components and write `.solution-manifest.json`, present summary. Reuses `references/solution-api-patterns.md`.
 - `export-solution`: 7-step workflow — verify prerequisites, identify solution (from `.solution-manifest.json` or user input), confirm managed vs unmanaged export (irreversible choice), trigger `ExportSolutionAsync`, poll via `scripts/poll-async-operation.js`, download and decode solution zip via `DownloadSolutionExportData`, verify zip contains `Solution.xml`. Reuses `scripts/poll-async-operation.js` and `references/solution-api-patterns.md`.