add-dataverse

**📋 Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first.

# Add Dataverse

Two paths:

- **Existing tables only** — skip to Step 5 (just runs `npx power-apps add-data-source` per table)
- **New / extended tables** — full workflow with Web API mutations in dependency order

## Workflow

1. Verify project & auth → 2. Resolve plan/operation manifest → 3. Setup Dataverse Web API auth → 4. Validate manifest or reconcile live metadata → 5. Execute sequential metadata phases → 6. Add data sources → 6b. Publish fallback customizations → 6c. Verify tables → 6d. Write manifest → 7. Inspect generated files → 8. Type-check → 8.5. Offline profile reconciliation → 9. Summary

---

### Step 1 — Verify project & auth

Confirm Power Apps mobile app:

```bash
test -f power.config.json && test -f app.config.js
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$(node -e \"console.log(require('./power.config.json').environmentId)\")"
```

Capture the **environment URL** (`https://orgXXX.crm.dynamics.com`), **environment ID**, and **tenant ID** from `resolve-environment.js` — needed for Step 3. If only the environment URL is available, pass that URL instead of the ID.

### Step 2 — Resolve plan

Look for `native-app-plan.md` in the project root:

```bash
test -f native-app-plan.md
```

Before reading plan content, inspect `$ARGUMENTS` for the five fast-path
artifact flags in Step 2a. When all are present, only confirm
`native-app-plan.md` exists for hash validation; do not parse its Data Model
section or build operations/service lists from Markdown.

**If present and `<operation_manifest_mode> = fallback`:** read the
`## Data Model` section. Extract:
- The target reconciliation table (`reuse` / `extend` / `create` / `adapt` / `defer` decisions and evidence)
- The Mermaid ER diagram (informational)
- The "Creation Order" tier list
- Every table referenced by `## Screens`, identity resolution, related-entity fields, forms, dashboards, or shared hooks, including standard reused tables such as `systemuser`, `contact`, and `account`

Build `SERVICE_REQUIRED_TABLES` as the union of:
1. every non-deferred row in Target Reconciliation (`reuse`, `extend`, `create`, or `adapt`);
2. every table in Creation Order;
3. every table named by screen/hook data requirements.

**Hard rule:** `reuse` means "do not mutate schema"; it does **not** mean "skip generated service." If app code reads or writes a reused table, that table must be in `SERVICE_REQUIRED_TABLES`.

Carry forward any `adapt` (auto-renamed) and `defer` (out-of-scope this run) decisions with their recorded reasons, and apply the alias map to every name you use. A data-modelling conflict never halts this skill — it resolves to `adapt` or `defer` and is reported in Step 9.

**If absent:** check `$ARGUMENTS` for diagram hints (`*.png`, `*.jpg`, `*.jpeg` filename, `erDiagram` keyword, `||--o{` cardinality syntax). 

- **Diagram hint present** → Path A (Step 2.5).
- **No hint AND `$ARGUMENTS` describes what the app does** (the typical case) → silently take Path B (Step 2.6 — spawn architect). No prompt.
- **No hint AND `$ARGUMENTS` is empty / non-descriptive** → only then prompt with `AskUserQuestion`:

  > "How would you like to define the data model?
  > (a) I have an existing ER diagram to upload (PNG/JPG path, Mermaid syntax, or text description)
  > (b) Let the data-model-architect agent analyze and propose one (default)
  > (c) Cancel — I'll plan it elsewhere first"

  Default the answer to (b) so empty/cancel input auto-proceeds. The 99% case (user gave a description but no diagram) skips this prompt entirely.

#### Step 2a — Approved operation-manifest fast path

When `$ARGUMENTS` supplies all five paths below, record
`<operation_manifest_mode> = candidate`:

- `--schema-contract <working_dir>/.tmp/dataverse-schema-contract.json`
- `--approval-receipt <working_dir>/.tmp/mobile-plan-status.json`
- `--execution-reconciliation <working_dir>/.tmp/dataverse-execution-reconciliation.json`
- `--operation-manifest <working_dir>/.tmp/dataverse-operation-manifest.json`
- `--publish-checkpoint <working_dir>/.tmp/dataverse-publish-pending.json`

Do not reconstruct tables, columns, relationships, keys, payloads, tiers, or
service requirements from Markdown on this path. The gate-owned approval receipt binds
the exact structured contract content/hash, final plan hash, and final
screen/service dependency list; `native-app-plan.md` remains the human review
artifact.

An entirely absent fast-path handoff means
`<operation_manifest_mode> = fallback` and preserves the standalone workflow
below, beginning with Step 2 initialization. A partially supplied handoff, or
a supplied manifest/contract/reconciliation/checkpoint that is malformed, stale,
incomplete, or bound to different context/files, must fail closed: print the
exact validation errors and return control to the orchestrator. Never jump to
Step 4 without Step 2 initialization, partially trust a candidate, or mix its
operations with agent-derived operations.

### Step 2.5 — Path A: Parse user-provided diagram

Used when the user has an existing diagram from another tool (Visio, dbdiagram.io, screenshot, hand-drawn).

Accept three input formats:

| Format | How |
|---|---|
| **Image path** (`*.png` / `*.jpg` / `*.jpeg`) | Use `Read` on the file path. The vision-capable model extracts entities, columns, relationships. |
| **Mermaid syntax** | User pastes a `erDiagram` block in chat. Parse the entities, columns, and `\|\|--o{` cardinalities directly. |
| **Text description** | User types a structured description ("Account has many ServiceVisits; each ServiceVisit has many WorkItems and Photos"). Spawn `data-model-architect` agent in `parse-only` mode with the text as input. |

Whichever format, normalize into the same structure used by the planner agent:

```yaml
publisherPrefix: <from detected publisher prefix or user>
tables:
  - logicalName: contoso_servicevisit