---

name: integrate-webapi description: >- Integrates Power Pages Web API into a site's frontend code with proper permissions and deployment. Orchestrates the full integration lifecycle: code integration, table permissions setup, and deployment for Dataverse CRUD operations. Use when the user wants to add Web API calls, connect to Dataverse, or add data fetching to their frontend. user-invocable: true allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList model: opus

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Integrate Web API

Integrate Power Pages Web API into a code site's frontend. This skill orchestrates the full lifecycle: analyzing where integrations are needed, implementing API client code for each table, configuring permissions and site settings, and deploying the site.

Core Principles

• First table sequential, then parallel: The first table must be processed alone because it creates the shared powerPagesApi.ts client. Once that exists, remaining tables can be processed in parallel since each creates independent files (types, service, hooks).
• Parallelize independent agents: The table-permissions-architect and webapi-settings-architect agents are independent — invoke them in parallel rather than sequentially.
• Permissions require deployment: The .powerpages-site folder must exist before table permissions and site settings can be configured. Integration code can be written without it, but permissions cannot.
• AI-only read mode is opt-in: When invoked by another skill (e.g. /add-ai-webapi) with the [AI-READ-ONLY] sentinel in $ARGUMENTS, the flow produces read-only code and hardens the settings/permissions for AI summarization reads. See Phase 1.6 for the contract. Human invocations never trigger this mode.
• Use TaskCreate/TaskUpdate: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.

Prerequisites:

• An existing Power Pages code site created via /create-site
• A Dataverse data model (tables/columns) already set up via /setup-datamodel or created manually
• The site must be deployed at least once (.powerpages-site folder must exist) for permissions setup

Initial request: $ARGUMENTS

---

Workflow

1. Verify Site Exists — Locate the Power Pages project and verify prerequisites
2. Explore Integration Points — Analyze site code and data model to identify tables needing Web API integration
3. Review Integration Plan — Present findings to the user and confirm which tables to integrate
4. Implement Integrations — Use the webapi-integration agent for each table
5. Verify Integrations — Validate all expected files exist and the project builds successfully
6. Setup Permissions & Settings — Choose permissions source (upload diagram or let the architects analyze), then configure table permissions and Web API site settings with case-sensitive validated column names
7. Review & Deploy — Ask the user to deploy the site and invoke /deploy-site if confirmed

---

Phase 1: Verify Site Exists

Goal: Locate the Power Pages project root and confirm that prerequisites are met

Actions:

1.1 Locate Project

Look for powerpages.config.json in the current directory or immediate subdirectories to find the project root. Use your file-search tool (e.g., Glob with patterns powerpages.config.json and */powerpages.config.json) rather than a shell-specific command.

If not found: Tell the user to create a site first with /create-site.

1.2 Read Existing Config

Read powerpages.config.json to get the site name.

1.3 Detect Framework

Read package.json to determine the framework (React, Vue, Angular, or Astro). See ${PLUGIN_ROOT}/references/framework-conventions.md for the full framework detection mapping.

1.4 Check for Data Model

Look for .datamodel-manifest.json to discover available tables:

**/.datamodel-manifest.json

If found, read it — this is the primary source for table discovery.

1.5 Check Deployment Status

Look for the .powerpages-site folder:

**/.powerpages-site

If not found: Warn the user that the permissions phase (Phase 6) will require deployment first. The integration code (Phases 2–5) can still proceed.

1.6 Detect AI-only read mode (skill-to-skill invocation)

Inspect $ARGUMENTS. If the text begins with the sentinel [AI-READ-ONLY], the caller is another skill (typically /add-ai-webapi) that has already analysed the site and decided which tables need Layer 1/2 prerequisites for AI summarization reads. Parse the following structured tokens out of $ARGUMENTS:

| Token | Required | Meaning | |-------|----------|---------| | mode=ai-read-only | Yes | Confirms the posture; any other value is rejected with an error. | | primary=<logical_name> | Yes | The primary table being summarised. Missing → stop and report the contract violation to the caller. | | tables=<csv> | Yes | Comma-separated list of all tables in scope (primary + every $expand target). | | expand-targets=<csv> | No | Sub-list of tables that are $expand targets; defaults to empty. | | caller=<skill-name> | No | Informational — used in commit messages and the final summary. |

When the sentinel is present:

• Set an internal flag AI-only read mode = true that every downstream phase consults.
• Skip the Phase 3 interactive table confirmation and use the provided tables list verbatim (user has already confirmed in the caller).
• The Phase 4.1 webapi-integration prompt restricts operations to read-only (list + get by id).
• The Phase 6 Path B agent prompts apply the hardened AI-only posture documented in each agent's "AI-only read mode" section.
• The Phase 6 Path A script invocations use --read only for table permissions and omit primary keys / relationship Navigation Properties from Webapi/<table>/fields.
• No AskUserQuestion prompts are issued for Phase 3 or Phase 6.2 — the caller owns those decisions.
• Defer all git commits to the caller. Skip Phase 4.4 (git add -A && git commit) and Phase 6.5 (permissions/settings commit) entirely. The caller is batching changes into one or two commits at orchestrator-defined milestones; an unprompted commit here turns one logical change into three. Print the file lists you would have committed so the caller can reproduce them.
• Suppress the end-of-skill deploy prompt. Skip Phase 6.1 (deploy-now ask when .powerpages-site is missing — the caller has already gated on this), Phase 7.3 (final deploy ask), and Phase 7.4 (post-deploy notes). The caller owns the single end-of-orchestration deploy decision; nesting deploy prompts inside the delegation gives the user 2–3 redundant asks per run. Return the integration summary (Phase 7.2) without trailing deploy/notes.

When the sentinel is absent: proceed exactly as today (full CRUD, full interactive flow, auto-commit, deploy prompt). This is the regression guard — no human invocation changes behavior.

Output: Confirmed project root, framework, data model availability, deployment status, and (if sentinel present) parsed AI-read-only contract.

---

Phase 2: Explore Integration Points

Goal: Analyze the site code and data model to identify all tables needing Web API integration

Actions:

Use the Explore agent (via Task tool with agent_type: "explore") to analyze the site code and data model. The Explore agent should answer these questions:

2.1 Discover Tables

Ask the Explore agent to identify all Dataverse tables that need Web API integration by examining:

• .datamodel-manifest.json — List of tables and their columns
• src/**/*.{ts,tsx,js,jsx,vue,astro} — Source code files that reference table data, mock data, or placeholder API calls
• Existing /_api/ fetch patterns in the code
• TypeScript interfaces or types that map to Dataverse table schemas
• Component files that display or manipulate data from Dataverse tables
• Mock data files or hardcoded arrays that should be replaced with API calls
• TODO or FIXME comments mentioning API integration

Prompt for the Explore agent:

"Analyze this Power Pages code site and identify all Dataverse tables that need Web API integration. Check .datamodel-manifest.json for the data model, then search the source code for: mock data arrays, hardcoded data, placeholder fetch calls to /_api/, TypeScript interfaces matching Dataverse column patterns (publisher prefix like cr*_), TODO/FIXME comments about API integration, and components that display table data. For each table found, report: the table logical name, the entity set name (plural), which source files reference it, what operations are needed (read/create/update/delete), and whether an existing API client or service already exists in src/shared/ or src/services/. Also check if src/shared/powerPagesApi.ts already exists."

When AI-only read mode is active (Phase 1.6 flag set): append the following to the prompt above:

"The caller has specified AI-READ-ONLY mode for tables [tables from sentinel] (primary=[primary], expand-targets=[expand-targets]). Operations needed for every table in that list = read only. Do NOT report create/update/delete call sites or mock-data replacement candidates. For each $expand target, also report the columns the primary's code $selects on that expansion (these become the minimal fields list)."

2.2 Identify Existing Integration Code

The Explore agent should also report:

• Whether src/shared/powerPagesApi.ts (or equivalent API client) already exists
• Which tables already have service files in src/shared/services/ or src/services/
• Which tables already have type definitions in src/types/
• Any framework-specific hooks/composables already created

This avoids duplicating work that was already done.

2.3 Compile Integration Manifest

From the Explore agent's findings, compile a list of tables needing integration:

| Table | Logical Name | Entity Set | Operations | Files Referencing | Existing Service | |-------|-------------|-----------|------------|-------------------|-----------------| | Products | cr4fc_product | cr4fc_products | CRUD | ProductList.tsx, ProductCard.tsx | None | | Categories | cr4fc_category | cr4fc_categories | Read | CategoryFilter.tsx | None |

Output: Complete integration manifest listing all tables, their operations, referencing files, and existing service status

---

Phase 3: Review Integration Plan

Goal: Present the integration manifest to the user and confirm which tables to integrate

Actions:

3.1 Present Findings

Show the user:

1. The tables that were identified for Web API integration
2. For each table: which files reference it, what operations are needed
3. Whether a shared API client already exists or needs to be created
4. Any tables that were skipped (already have services)

3.2 Confirm Tables

<!-- gate: integrate-webapi:3.2.confirm-tables | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · integrate-webapi:3.2.confirm-tables): Final say on which tables get Web API integration code (client, types, services, hooks).

Trigger: Explore agent surfaced candidate tables in Phase 3.1. Why we ask: Auto-selecting all tables can generate orphaned TypeScript files for tables the user never intended to expose via Web API. Cancel leaves: Nothing — no service/type/hook files written yet.

When AI-only read mode is active (Phase 1.6 flag set): skip this step entirely. Use the tables list parsed from the sentinel verbatim — the caller has already confirmed the selection with the user. Do not issue an AskUserQuestion.

Otherwise, use AskUserQuestion to