/setup-offline-profile

name: setup-offline-profile
description: Use when the user wants to enable offline mode for a Power Apps mobile app and create a Mobile Offline Profile in Dataverse — designs per-table row scope, relationships, columns, and sync frequency through a 3-gate approval flow.
user-invocable: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, EnterPlanMode, ExitPlanMode, Task
model: opus

> **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.

**References:**

• [offline-profile-schema.md](${PLUGIN_ROOT}/shared/references/offline-profile-schema.md) — Dataverse entity field map
• [dataverse-offline-api.md](${PLUGIN_ROOT}/shared/references/dataverse-offline-api.md) — Web API recipes for profile / item / association POSTs
• [offline-profile-reconciliation.md](${PLUGIN_ROOT}/shared/references/offline-profile-reconciliation.md) — the `schemaColumns` baseline this skill writes + the lifecycle delta check that consumes it

Setup Offline Profile

End-to-end wizard for creating a Dataverse Mobile Offline Profile that the app (and any other compatible Power Apps client) can use to download data for offline access.

**Scope of v0**: configuration only. This skill creates records in the existing Dataverse Mobile Offline Profile tables (`mobileofflineprofile`, `mobileofflineprofileitem`, `mobileofflineprofileitemassociation`) and writes the full app-level offline config — profile metadata, per-table scope, and the temporary SDK-workaround fields — to `offline-profile.json`. **This skill does NOT modify `power.config.json`** (that file is owned by `pa app init` and its schema is controlled upstream). The template already bundles `@microsoft/power-apps-native-offline`; `@microsoft/power-apps-native-host` consumes the profile and owns local SQLite access, queued synchronization, reconnect behavior, and status UX. This skill does not scaffold duplicate app-owned offline runtime code.

**Out of scope for v0**:

• Custom filter mode (`recorddistributioncriteria=3`, savedquery picker) — defer to v0.5
• User/team membership assignment — split into `/assign-offline-profile`
• Row-count download estimation — split into `/preview-offline-scope`

App-root binding

Before entering the wizard, and before any project read or command, execute [app-working-directory.md](${PLUGIN_ROOT}/shared/references/app-working-directory.md). Resolve one absolute `working_dir`: inherit a child invocation's owner root or use the direct invocation's explicit `--working-dir`/initial cwd per that contract. Missing or conflicting child context returns `NEEDS_CONTEXT`, never a launch-cwd fallback. Bind every shell call and file tool, including references and retries, to this root; file tools use absolute `<working_dir>/...` paths.

Retain the selected environment ID/URL/tenant and supplied answers as invocation context. Re-supply the absolute `PLUGIN_ROOT` and required values in each fresh call; prior shell variables do not persist. Forward the same root and identity to the architect and prerequisite helper. Entry approval is not permission to skip the wizard's offline gates. A `--plan-only` or planning-phase caller returns `NEEDS_CONTEXT: offline setup requires an implementation-phase invocation` before entering this mutating wizard.

Workflow

1. Verify project & auth → 2. Resolve mode (create vs extend) → 3. Spawn architect agent → **Gate 1** (table prerequisites) → 4. Run the internal `enable-tables-offline` workflow if needed → 5. POST profile shell → **Gate 2** (per-table row scope) → 6. POST profile items → **Gate 3** (relationships + columns + sync) → 7. POST associations → 8. Validate + publish → 9. Persist artifacts → 10. Summary

---

Step 1 — Verify project & auth

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
if [ ! -f power.config.json ] || [ ! -f app.config.js ]; then
  echo "BLOCKED: working_dir is not an initialized app" >&2
  exit 1
fi
environment_id=$(node -p "require('./power.config.json').environmentId || ''") || {
  echo "BLOCKED: unreadable power.config.json" >&2; exit 1;
}
if [ -z "$environment_id" ]; then
  echo "NEEDS_CONTEXT: selected app has no environmentId" >&2; exit 1;
fi
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$environment_id" --no-cache --require-tenant

Require the resolved environment ID, HTTPS URL, and tenant to match any supplied owner context. Capture them as `<selected-environment-id>`, `<envUrl>`, and `<tenantId>`. A mismatch returns `NEEDS_CONTEXT`; do not switch environment or account to proceed. Pass `--tenant-id "<tenantId>"` to every Dataverse request, including copied reference commands and retries.

Locate `<working_dir>/.datamodel-manifest.json` or `<working_dir>/docs/plan-artifacts/.datamodel-manifest.json` with absolute file tools. Keep the selected absolute manifest path in invocation context for the architect (Step 3) and artifact updates (Step 9); never search another app.

**Web-only target detection** — Mobile Offline Profiles only apply to native targets (iOS/Android). If the project is web-only, the profile will be created in Dataverse but **the generated app will never use it**:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
# Inspect platforms declared in app.config.js
node -e "
const c = require('./app.config.js');
const platforms = c?.expo?.platforms ?? [];
const hasNative = platforms.includes('ios') || platforms.includes('android');
console.log(JSON.stringify({ platforms, hasNative }));
"

| `hasNative` | Action | |---|---| | `true` (has `ios` and/or `android`) | Continue normally | | `false` (web-only or no platforms) | Print: `⚠ This project only targets web — Mobile Offline Profiles don't apply (they require iOS/Android). Continuing will