setup-datamodel

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

# Set Up Dataverse Data Model

Guide the user through creating Dataverse tables, columns, and relationships for their Power Pages site. Follow a systematic approach: verify prerequisites, obtain a data model (via AI analysis or user-provided diagram), review and approve, then create all schema objects via OData API.

## Core Principles

- **Never create without approval**: Always present the full data model proposal and get explicit user confirmation before making any Dataverse changes.
- **Use TaskCreate/TaskUpdate**: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
- **Resilient execution**: Refresh tokens proactively, check for existing tables before creating, and report failures without automated rollback.

**Initial request:** $ARGUMENTS

---

## Phase 1: Verify Prerequisites

**Goal**: Confirm PAC CLI authentication, acquire an Azure CLI token, and verify API access

**Actions**:

1. Create todo list with all 8 phases (see [Progress Tracking](#progress-tracking) table)
2. Follow the prerequisite steps in `${CLAUDE_PLUGIN_ROOT}/references/dataverse-prerequisites.md` to verify PAC CLI auth, acquire an Azure CLI token, and confirm API access. Note the environment URL as `<envUrl>` for subsequent script calls.

**Output**: Verified PAC CLI auth, valid Azure CLI token, confirmed API access, `<envUrl>` noted

---

## Phase 2: Choose Data Model Source

**Goal**: Determine whether the user will upload an existing ER diagram or let AI analyze the site

**Actions**:

<!-- gate: setup-datamodel:2.source | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · setup-datamodel:2.source):** Decide whether the user uploads an existing ER diagram or the data-model-architect agent infers the model. Choice routes the rest of the skill into Path A vs Path B.
>
> **Trigger:** Entering Phase 2.
> **Why we ask:** Auto-picking either path can run a multi-minute architect agent against the wrong intent (Path B) or skip Dataverse-existence checks (Path A).
> **Cancel leaves:** Nothing — no Dataverse calls made yet.

1. Ask the user how they want to define the data model using the `AskUserQuestion` tool:

   **Question**: "How would you like to define the data model for your site?"

   | Option | Description |
   |--------|-------------|
   | **Upload an existing ER diagram** | Provide an image (PNG/JPG) or Mermaid diagram of your existing data model |
   | **Let the Data Model Architect figure it out** | The Data Model Architect will analyze your site's source code and propose a data model automatically |

2. Route to the appropriate path:

### Path A: Upload Existing ER Diagram

If the user chooses to upload an existing diagram:

1. Ask the user to provide their ER diagram. Supported formats:
   - **Image file** (PNG, JPG) — Use the `Read` tool to view the image and extract tables, columns, relationships, and cardinalities from it
   - **Mermaid syntax** — The user can paste Mermaid ER diagram text directly in chat
   - **Text description** — A structured list of tables, columns, and relationships

2. Parse the diagram into the same structured format used by the data-model-architect agent:
   - Publisher prefix (ask the user, or retrieve from the environment via `pac env who`)
   - Table definitions: `logicalName`, `displayName`, `status` (new/modified/reused), `columns`, `relationships`
   - Column definitions: `logicalName`, `displayName`, `type`, `required`
   - Relationship definitions: type (1:N or M:N), referenced/referencing tables

3. Query existing Dataverse tables (same as Phase 3 would) to mark each table as `new`, `modified`, or `reused`.

4. Generate a Mermaid ER diagram from the parsed data (if the user provided an image or text) for visual confirmation.

5. Proceed directly to **Phase 4: Review Proposal** with the parsed data model.

### Path B: Let the Data Model Architect Figure It Out

If the user chooses to let the Data Model Architect figure it out, proceed to **Phase 3: Invoke Data Model Architect** (the existing automated flow).

**Output**: Data model source chosen and, for Path A, parsed data model ready for review

---

## Phase 3: Invoke Data Model Architect

**Goal**: Spawn the data-model-architect agent to autonomously analyze the site and propose a data model

**Actions**:

1. Use the `Task` tool to spawn the `data-model-architect` agent. This agent autonomously:
   - Analyzes the site's source code to infer data requirements
   - Queries existing Dataverse tables via OData GET requests
   - Identifies reuse opportunities (reuse, extend, or create new)
   - Proposes a complete data model with an ER diagram

2. Spawn the agent:

   ```
   Task tool:
     subagent_type: general-purpose
     prompt: |
       You are the data-model-architect agent. Follow the instructions in
       the agent definition file at:
       ${CLAUDE_PLUGIN_ROOT}/agents/data-model-architect.md

       Analyze the current project and Dataverse environment, then propose
       a complete data model. Return:
       1. Publisher prefix
       2. Table definitions (logicalName, displayName, status, columns, relationships)
       3. Mermaid ER diagram
   ```

3. Wait for the agent to return its structured proposal before proceeding.

**Output**: Structured data model proposal from the agent (publisher prefix, table definitions, ER diagram)

---

## Phase 4: Review Proposal

**Goal**: Present the data model proposal to the user and get explicit approval before creating anything

**Actions**:

### 4.1 Present Proposal

Present the data model proposal directly to the user as a formatted message, including:

- Publisher prefix
- All proposed tables with columns (logical names + display names)
- Relationship descriptions
- Mermaid ER diagram
- Which tables are new vs. modified vs. reused

### 4.2 G