setup-datamodel

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` - if it outputs a message, show it to the user before proceeding. **📋 Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first. # Set Up Data Model + Connectors **Entry routing:** use the shared [App feature entry points](../../shared/shared-instructions.md#app-feature-entry-points) preflight before the workflow below. **Invocation scope:** follow [Data-source invocation scope](../../shared/shared-instructions.md#data-source-invocation-scope) before any project read or the workflow below. This standalone data-only workflow does not require a complete app plan. It proposes and approves only the current schema/connector delta; preserve existing app sections without invoking full-app planning or screen generation. When called by an owner, retain its explicit current request, absolute root, phase, and scope, and return proposals or verified results to that owner. Combined orchestrator for standalone data source planning. Designs the Dataverse schema, plans connectors, gets approval on both, then delegates execution to `/add-dataverse` and `/add-connector`. | Use this skill when | Use `/add-dataverse` directly when | |---|---| | Standalone schema + connector design (initialized app; data plan optional) | The plan already exists and you just need to apply tables + generate services | | You have an existing ER diagram (image / Mermaid / text) to import | `/create-mobile-app` is invoking this as a sub-step with approved scoped context | | Re-planning the schema or connectors mid-project | You only need to add a single table or a single connector | ## Workflow 1. Resolve project root & verify auth → 2. Design data model → 3. Plan connectors → 4. Combined approval → 5. Execute additions/refreshes → 6. Execute connectors → 6.25 Retire approved bindings → 6.5 Reconcile offline profile → 7. Reconcile inventory & summarize --- ### Phase 1 — Verify Project & Auth Resolve one absolute `working_dir` before reading project files or discovering the environment: - For a nested call, inherit the owner's absolute `working_dir`. If `--working-dir` is also supplied, both must resolve to the same directory; a mismatch returns `NEEDS_CONTEXT` before any project or cloud work. - For a direct call, resolve an explicit `--working-dir` against the invocation directory. Only a direct call without an override may use that invocation directory as its project root. - Require the selected directory to exist, normalize it to one absolute path, and retain it for this invocation. A missing nested owner path is an error: never fall back to the shell's current directory or search neighboring apps. All relative app paths below, including diagram inputs, `native-app-plan.md`, `_dm_section.md`, `.datamodel-manifest.json`, `offline-profile.json`, and `memory-bank.md`, are relative to this resolved root, not a later tool's cwd. Use absolute paths with file tools. Begin every shell invocation that reads or writes app-local files with the single-quoted fail-closed app-root guard; shell state does not carry across tool calls. Confirm the selected root is a Power Apps mobile app: For `--plan-only` or a planning-phase handoff, perform the file/environment checks read-only and use the shared proposal-only environment-context rule. The same non-persisting lookup is used before approval in a normal invocation. Incomplete or conflicting context returns `NEEDS_CONTEXT` after read-only recovery; never retry without the safety flags or redirect into app configuration. ```bash cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; } if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then printf '%s\n' 'ERROR: selected working directory is not an initialized mobile app' >&2 exit 1 fi environment_id="$(node -p "require('./power.config.json').environmentId || ''")" || exit 1 if [ -z "$environment_id" ]; then printf '%s\n' 'ERROR: selected app has no environmentId' >&2 exit 1 fi node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant ``` Stop on failure; do not switch directories or re-scaffold. Capture the **environment URL**, **environment ID**, and **tenant ID** for this root for Phase 5. Pass this same absolute root in every planner/skill handoff and on retries. ### Phase 2 — Design Data Model **Telemetry checkpoint: `design_dataverse_schema`** Check whether the request needs Dataverse schema first; connector-only requests take Path C. Otherwise check `$ARGUMENTS` for diagram hints (`*.png`, `*.jpg`, `erDiagram`, `||--o{`). If present, take Path A. If a Dataverse requirement is already supplied, take Path B for a read-only proposal. If the choice is still unknown, ask: > "How would you like to define the data model?" | Option | What happens | |---|---| | Upload an existing ER diagram | Provide a PNG/JPG path, Mermaid block, or text description | | Let the Data Model Architect propose one (default) | Spawns `data-model-architect` agent to infer from requirements | | Skip — no Dataverse tables needed | Jump to Phase 3 | Recommend "architect propose" only when Dataverse schema is needed. Connector-only requirements take Path C without inventing Dataverse tables. Empty/cancel input does not approve a choice; wait for an answer or stop. For Paths A and B, read and execute [dataverse-change-planning.md](../../shared/references/dataverse-change-planning.md). The foreground owns scoped discovery, compact-evidence validation, and recovery; pass `Dataverse planning mode: required` to the architect, never the legacy live-discovery path. Preserve the current request, absolute root, and proposal-only mode through every handoff. Path C, removal-only work, and a retained-service-only refresh skip schema planning and its artifacts. #### Artifact storage rules for PDFs and signatures When requirements mention signatures, sign-off, ink, drawings, generated PDFs, exported reports, evidence packets, or retained documents, make the storage target explicit in `## Data Model` before approval: | User signal | Dataverse model implication | |---|---| | "capture signature", "sign off", "approval signature", "ink" | Ask whether retention is needed; only when Dataverse retention is selected, reuse or propose an Image/File column or child Evidence/Signature table | | "generate PDF", "export report", "evidence packet", "certificate PDF" | Ask whether the generated PDF should be retained. If yes, use a Dataverse File column, usually on the parent record or a child Evidence/Attachment table. If no, document on-device/share-only behavior and add no column. | | "upload PDF", "attach file", "import document" | File column or child Attachment table with lookup to parent | | "view PDF" | Store or reference an HTTPS URL if the app has a durable source. Native PDF viewer 0.2.9+ also supports local `file://` URIs; `content://`, `blob:`, and `http://` remain unsupported. | PDF content must never be modeled as long text/base64 text. Use Dataverse File columns for retained PDFs. Signature PNGs may use Image columns when the generated service supports image payloads; use File columns or child Evidence rows when the capture should behave like an attachment. #### Path A — Parse user-provided diagram Accept PNG/JPG (use `Read` to view), Mermaid syntax (paste in chat), or text description. Parse tables, columns, and relationships as requested intent. Use the shared compact-evidence workflow to draft `_dm_section.md` and the normalized `.tmp/dataverse-schema-contract.json`; diagram names alone do not prove existing schema. Run the same decision validation as Path B before the combined Phase 4 approval; do not update the live plan yet. #### Path B — Spawn data-model-architect ``` Task: mobile-app:data-model-architect Prompt: You are the data-model-architect agent for a Power Apps mobile app. Requirements: <$ARGUMENTS or ask the user what the app does> Working directory: <working_dir> Output proposal: <working_dir>/_dm_section.md Plugin root: ${PLUGIN_ROOT} Phase: planning Proposal only: <true for --plan-only or a planning-phase caller> Dataverse planning mode: required Normalized Dataverse foreground planning snapshot (validator input only): <SNAPSHOT_PATH> Compact Dataverse architect evidence: <ARCHITECT_EVIDENCE_PATH> Structured schema contract output: <working_dir>/.tmp/dataverse-schema-contract.json Scope: <current requested delta and necessary dependencies; unrelated rows are context only> Native capabilities and connector ownership: <retained approved constraints> Follow your snapshot-only path. Return a ## Data Model section with Mermaid ER diagram, reuse/extend/create table, and dependency-tier ordering. If requirements mention signatures, pen/ink, generated PDFs, report exports, evidence packets, or uploaded documents, include the artifact storage target: on-device/share-only, Dataverse Image column, Dataverse File column, or child Evidence/Attachment table. Retained PDF content must use a File column, not long text/base64. ``` Handle structured Dataverse signals through the shared planning recovery before the generic `AGENTS.md` return protocol. Require both the section and normalized contract, then run the shared decision gate even for `DONE`/`DONE_WITH_CONCERNS`. If agents are unavailable, draft both artifacts inline from the same compact evidence and run the same validation. Keep the result as a proposal for Phase 4; stop on an unresolved blocker rather than treating the proposal as approved. #### Path C — No Dataverse Propose no Dataverse changes. Preserve any existing Data Model section; only use "None — no Dataverse tables needed" when the project has no Dataverse model. Continue to Phase 3 without overwriting the plan. ### Phase 3 — Plan Connectors **Telemetry checkpoint: `plan_connector_integrations`** Follow [`shared/references/connector-planning.md`](${PLUGIN_ROOT}/shared/references/connector-planning.md): 1. **Infer** — if `$ARGUMENTS` describes what the app does, scan for connector keywords. Build a candidate list. 2. **Confirm** — present via `AskUserQuestion`. Let the user add, remove, or confirm. 3. **Record** — build the `## Connectors` section. If the user provided no requirements context, ask: > "What does your app need to connect to? (e.g. SharePoint, Teams, email, Excel, OneDrive, Azure DevOps — or none)" ### Phase 4 — Combined Approval **Telemetry checkpoint: `approve_data_model_and_connectors`** For an existing data-only plan, compare current bindings with the proposal before writing it. Apply [data-source-removal.md](../../shared/references/data-source-removal.md) to classify and approve removals explicitly. Omitted tables are not automatic deletions; retain anything required by existing consumers. Report their required changes separately; the user may request existing `/edit-app` for consumer work, but this workflow does not invoke it automatically. For a Dataverse proposal from any path, require the current normalized contract and snapshot to pass `validate-dataverse-planning-decisions.js` with exit `0` before this gate. Revisions repeat validation, not broad discovery or another approval ceremony. Connector-only, retirement-only, and refresh-only proposals keep their own checks and must not reuse stale schema-planning artifacts. **Proposal-only exit:** if `--plan-only` is present or the caller's phase is planning, present the proposed Data Model, Connectors, and retirement/offline impact, then return to the caller and STOP before the execution approval below. Do not save `native-app-plan.md`, mint approval receipts, update the materialized manifest, or invoke Phases 5–7. A scratch proposal is not an applied plan. Approval to review the proposal does not override `--plan-only`; implementation requires a separate request without that flag and approval of its exact delta. Present the full plan for this data-source delta — data model + connectors — together in a single `EnterPlanMode` block. Distinguish retained context from additions, refreshes, and explicitly approved retirements. A current implementation-phase owner may supply the exact data approval instead; validate that it matches this proposal and return scope changes to that owner before writing. A saved plan or `--skip-planning` alone is not approval. ``` ## Plan: Data Sources ### Data Model [reuse/extend/create table] [Mermaid ER diagram] [creation order tiers] ### Connectors [connector table or "None"] Approve both to proceed with execution? ``` - **Approved** → save both approved sections to `native-app-plan.md`, preserving unrelated sections, then proceed to Phase 5. This applies to every Phase 2 path, including architect output and connector-only plans. - **Change data model** → loop back to Phase 2 for that section only, then re-present Phase 4 - **Change connectors** → loop back to Phase 3, then re-present Phase 4 - **Cancel** → stop without applying the proposed plan or data-source mutations. Save the accepted proposal into `<working_dir>/native-app-plan.md`; scratch `_dm_section.md` is not a second source of truth. Do not reuse operation manifests or approval receipts bound to the previous plan. The verified materialized manifest is updated after execution/verification, not by copying proposed rows. For approved Dataverse implementation, retain the shared planning paths and freeze the accepted `contract_sha256` and saved `plan_sha256` in `approved_scope`. This is not a create-flow receipt and does not grant unrelated native, connector, or screen approvals. ### Phase 5 — Execute Data Model **Telemetry checkpoint: `apply_dataverse_schema`** Invoke `/add-dataverse` with `--skip-planning` so it reads the approved plan directly without re-prompting: Apply only additions/refreshes here. Skip this phase for a removal-only delta; approved retirements have their own Phase 6.25 handoff. For a service-only refresh of an already registered table, use the leaf's `--refresh --data-source-name "<registered-name>"` branch and pass its exact registered identity in `approved_scope`; do not execute the schema-add handoff below for that row. For schema changes, retain the normal handoff below. ``` Invoke skill: /add-dataverse Context: MOBILE_APP_ORCHESTRATING=1 orchestrator: setup-datamodel working_dir: <working_dir> phase: implementation offline_reconciliation_owner: setup-datamodel planning_snapshot: <SNAPSHOT_PATH> architect_evidence: <ARCHITECT_EVIDENCE_PATH> schema_contract: <working_dir>/.tmp/dataverse-schema-contract.json approved_scope: <approved Data Model delta and answers, contract_sha256, plan_sha256> Arguments: --working-dir '<working_dir>' --plan-section '<working_dir>/native-app-plan.md#data-model' --skip-planning ``` `/add-dataverse` creates tables in tier order within this scope, adds only approved missing bindings or refreshes approved retained services, publishes customizations when needed, writes `.datamodel-manifest.json`, and type-checks. It validates the scoped planning context and performs fresh live reconciliation; do not send partial create-only fast-path flags. Wait for it to return before Phase 6. **Cross-entity reads from the screen plan** — the approved `### Cross-entity Reads` subsection contains formatted lookups, bounded chained fetches, or `external-projection-required` blockers. `/add-dataverse` never synthesizes calculated/formula definitions through code. A user-supplied, maker-created computed column is validated as an existing dependency during reconciliation before it can be reused. Skip if Phase 2 chose Path C (no Dataverse). ### Phase 6 — Execute Connectors **Telemetry checkpoint: `generate_connector_data_sources`** Read `## Connectors` from `native-app-plan.md`. For each approved added/refreshed connector row (not retained or retiring rows), invoke `/add-connector`: Separate the operation before dispatch: an added row takes the normal handoff; a refreshed row adds `--refresh --data-source-name "<registered-name>"` and includes the verified API/dataset/connection identity in `approved_scope`. Do not infer the registered name from the connector display label. The refresh branch must return without connection creation or `add-data-source`. **Added source only:** ``` Invoke skill: /add-connector Context: MOBILE_APP_ORCHESTRATING=1 orchestrator: setup-datamodel working_dir: <working_dir> phase: implementation approved_scope: <approved connector row and answers> Arguments: --working-dir '<working_dir>' --connector <api-name> ``` **Retained-source refresh only:** use this separate handoff, never the add block. ```text Invoke skill: /add-connector Context: MOBILE_APP_ORCHESTRATING=1 orchestrator: setup-datamodel working_dir: <working_dir> phase: implementation approved_scope: <refresh operation, exact registered name, verified API/dataset/resource and connection ID/reference> Arguments: --working-dir '<working_dir>' --connector <verified-api-id> --refresh --data-source-name "<registered-name>" ``` Run sequentially. Skip if `## Connectors` is "None". ### Phase 6.25 — Retire unused app bindings For each explicitly approved retirement, invoke the matching leaf with `--remove`, `MOBILE_APP_ORCHESTRATING=1`, `orchestrator: setup-datamodel`, `phase: implementation`, `working_dir: <working_dir>`, the argument `--working-dir '<working_dir>'`, and its `approved_scope`. Follow [data-source-removal.md](../../shared/references/data-source-removal.md). This standalone data-only flow does not edit consumers: if any remain, stop and report their integration work to the user or current owner instead of breaking them. The user may separately request `/edit-app`; never route there automatically. Verify the CLI cleanup and reconcile the actual remaining generated-service snapshot and app manifest before the summary. No retirement set means skip. Preserve each leaf's `offlineRetirement` outcome from the shared removal contract, including unresolved outcomes recorded in memory-bank by an earlier attempt. App-binding cleanup and offline-profile migration have separate completion states. ### Phase 6.5 — Offline profile reconciliation **Telemetry checkpoint: `reconcile_offline_profile`** If Phase 5 created or extended Dataverse tables, an existing Mobile Offline Profile may now be missing those tables/columns. Phase 5 passes a complete scoped handoff with `offline_reconciliation_owner: setup-datamodel`; together with `--skip-planning`, that makes this orchestrator the owner instead of running the leaf's Step 8.5 check twice. The flag alone is not enough. Skip the addition check when Phase 2 chose Path C (no Dataverse), but never discard a recorded `offlineRetirement` outcome. Run the local, no-network delta check: ```bash