setup-offline-profile

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 — read first.

References:

• offline-profile-schema.md — Dataverse entity field map
• dataverse-offline-api.md — Web API recipes for profile / item / association POSTs
• 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. 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; }

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:

STOP conditions:

• No power.config.json → "Run /create-mobile-app first."
• Neither .datamodel-manifest.json nor docs/plan-artifacts/.datamodel-manifest.json → "Run /add-dataverse first — offline profiles require a data model."
• Environment resolution failure → standard auth recovery (az login --tenant <env-tenant> or provide environment URL directly; see shared-instructions.md).
• Web-only + user declines override → STOP. Print: Offline profile creation skipped — no native target.

Step 1a — Environment consistency check

Same as /add-dataverse Step 3a — verify power.config.json resolves and az can token for the target tenant. STOP if it cannot; user must re-auth with az login --tenant <env-tenant>.

Step 1b — Resume check

Read memory-bank.md ## Offline profile block. Decide based on status:

Resume flow — when memory-bank has status: in-progress AND the profile still exists:

1. GET /mobileofflineprofiles(<profileId>)?$expand=MobileOfflineProfile_MobileOfflineProfileItem to compute what's actually been committed:

   • 0 items → profile shell exists, items not yet POSTed. Resume from Step 6.
   • 1+ items, missing some from manifest → resume from Step 6, skipping items already present.
   • All items present, selectedcolumns empty on ≥1 → resume from Step 7 (PATCH).
   • All items present, all have selectedcolumns → resume from Step 8 (Publish).
   • componentstate=0 (Published) → memory-bank lies; treat as done.

2. Ask the user one consolidated AskUserQuestion (NOT a per-step approval):

   Resume from <computed step> on profile "<name>" (<profileId>)?
    
   Items already committed: <N> of <M>
   PATCHes already applied: <K>
   Published:               <yes|no>
    
   Options:
   - Resume from where it left off (recommended)
   - Start fresh — delete the half-built profile and re-run from Step 5
   - Cancel

3. On Resume → jump to the computed step. Skip already-committed items by matching selectedentitytypecode.

4. On Start fresh → DELETE /mobileofflineprofiles(<profileId>) (cascade-deletes items + associations), clear memory-bank section, continue to Step 2 as new.

5. On Cancel → STOP, leave memory-bank untouched.

Memory-bank checkpoint contract: the skill writes status: in-progress + profileId immediately after Step 5 (profile shell POST). Each subsequent step updates a lastSuccessfulStep: field so resume knows where to pick up. On BLOCKED: from any step, the skill leaves status: in-progress; on DONE, it writes status: done in Step 9c.

Idempotency on POST retries: if Step 6 re-POSTs an item with the same selectedentitytypecode against the same parent profile, Dataverse may return 409 Conflict ("duplicate"). The wrapper dataverse-request.js treats this as silent success via its looksLikeDuplicate logic — safe to re-attempt.

Step 2 — Resolve mode (create vs extend vs reconcile)

Telemetry checkpoint: resolve_offline_profile_mode

Print before starting:

"→ Checking for existing offline profiles in the environment…"

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
  "mobileofflineprofiles?\$select=mobileofflineprofileid,name,description,publishedon" \
  --tenant-id "<tenantId>"

Decision tree — evaluate in order:

Why row #2 is critical (empirical 2026-05-25): the chanel-rm and FCB Tracker test runs hit this case. Without this check, the skill cascade-deleted the pinned profile silently. After this patch, the user gets a clear three-way choice and delete is always an explicit action.

Extend mode (rows #2a, #4a) implementation: re-spawn the architect with Mode: extend, existingProfileId: <X>. The architect compares its current proposal to the on-server items + associations and outputs three lists: (i) items to ADD, (ii) items to PATCH (scope/columns/sync diffs), (iii) items to DELETE (in-server but not in current data model). Surface to the user at Gate 2. After approval, the skill issues incremental writes — no profile-shell POST.

Step 3 — Spawn architect agent

Telemetry checkpoint: design_offline_profile_scope

Print before starting:

"→ Spawning mobile-app:offline-profile-architect agent (read-only) to design the profile…"

Spawn via Task:

agent: mobile-app:offline-profile-architect
prompt:
  Owner: setup-offline-profile
  Phase: planning
  Working directory: <working_dir>
  Plugin root: ${PLUGIN_ROOT}
  Environment ID: <selected-environment-id>
  Environment URL: <envUrl>
  Tenant ID: <tenantId>
  Manifest path: <absolute manifest path within working_dir>
  Proposal output: <working_dir>/_offline_section.md
  Publisher prefix: <prefix>
  Mode: default

The agent returns _offline_section.md in the working directory. Read it. Parse its first-line status code:

• DONE → continue
• DONE_WITH_CONCERNS: <list> → surface concerns at Gate 2 / Gate 3 where relevant; continue
• NEEDS_CONTEXT: <missing> → resolve the missing context (most often: data model file absent), re-spawn once (cap: 2 retries). If still failing, STOP with the agent's reason.
• BLOCKED: <reason> → STOP, surface to user, do not silently retry.

Step 3.5 — Configuration review (interactive AskUserQuestion flow)

Telemetry checkpoint: review_offline_profile_configuration

Print before starting:

"→ Presenting the proposed offline profile configuration. You'll tap an option to accept, adjust, or cancel — no need to type."

The skill renders the proposal as a one-screen summary (read-only context) and then drives the decision through structured AskUserQuestion prompts — the same click-style pattern /create-mobile-app uses for its 4 plan gates. This replaces the older "type accept / plain-English edits / cancel" reply flow, which was hit-or-miss when users typed something the parser didn't recognize.

Step 3.5a — Print the summary (informational only)

Substitute real values from _offline_section.md and the architect output:

══════════════════════════════════════════════════════════════════════
 Mobile Offline Profile — Proposed Configuration
══════════════════════════════════════════════════════════════════════
 
PROFILE METADATA
  Name        : <proposed name>
  Description : <proposed description, or "(none)">
  Mode        : create-new | extend existing (<profileId>)
 
TABLE PREREQUISITES (IsAvailableOffline + ChangeTrackingEnabled)
  cr123_note   ❌/❌  → will be enabled
  cr123_visit  ✅/❌  → ChangeTracking will be enabled
  contact      ✅/✅  → no change
 
PER-TABLE CONFIG
 
  ▸ cr123_note (Organization rows, User's rows)
      Sync     : every 10 min
      Columns  : 12 (cr123_title, cr123_body, cr123_visitid, …, modifiedon, createdon)
 
  ▸ cr123_visit (Related rows only)
      Sync     : every 10 min
      Columns  : 8 (cr123_name, cr123_date, …, modifiedon)
 
  ▸ contact (All records)
      Sync     : every 60 min
      Columns  : 5 (fullname, emailaddress1, …, modifiedon)
 
RELATIONSHIPS (will be POSTed as mobileofflineprofileitemassociation rows)
  cr123_note   → cr123_note_visit   (links to cr123_visit)
  cr123_note   → cr123_note_image   (includes image bytes)
══════════════════════════════════════════════════════════════════════

No prompt is shown alongside this text — it's informational context, immediately followed by the interactive prompt below.

Step 3.5b — Top-level decision (single AskUserQuestion)

header   : Offline profile
question : "Accept the proposed offline profile configuration and publish to Dataverse?"
options  :
  - Accept and publish (Recommended)
  - Adjust before publishing
  - Cancel — abort, nothing is mutated

Outcomes:

Step 3.5c — Pick the areas to adjust (single AskUserQuestion, multiSelect)

header     : Adjust which
question   : "Which sections of the proposal do you want to change?"
multiSelect: true
options    :
  - Profile name or description
  - Per-table row scope (who's rows get synced)
  - Per-table sync interval
  - Per-table column selection

Whatever the user picks drives Step 3.5d. If they pick nothing (closing the dialog), treat that as a no-op and loop back to Step 3.5b.

Step 3.5d — Drill-down per area

For each area the user picked in 3.5c, run the corresponding sub-flow. Apply edits to an in-memory config copy as you go; nothing hits Dataverse until Step 3.5e.

Profile name or description — text prompt (free-form input, no enumeration possible):

"Type the new profile name, or skip to keep <current name>."

Then: "Type the new description, or skip to keep <current description>."

Validate name ≤ 100 chars; trim whitespace; reject empty.

Per-table row scope — one AskUserQuestion per table (batch up to 4 tables per call; 5+ tables → multiple calls):

header   : Scope <table>
question : "Row scope for `<table-logical-name>`?"
options  :
  - Related rows only (child of a parent table; default for pure children)
  - All records (default for shared catalogs like product / contact)
  - User's own rows (Organization-scoped + recordsownedbyme=true; default for personal transactional data)
  - Organization's rows (Organization-scoped, all owners — broadest non-All)

Map answers → recordDistributionCriteria (0=Related, 1=All, 2=Organization) + the recordsownedby* sub-flags. If the user picks "User's own rows" set recordsownedbyme=true; if "Organization's rows" leave all three sub-flags false.

Per-table sync interval — one AskUserQuestion per table:

header   : Sync <table>
question : "How often should `<table-logical-name>` sync?"
options  :
  - Every 5 min — hot transactional data (Recommended for tables users edit live)
  - Every 15 min — typical
  - Every 30 min — slower-moving
  - Every 60 min — static catalogs (lowest battery cost)

(Range is 5–1440 min server-side; custom values outside these four come via the Other free-text option that AskUserQuestion always provides — validate 5 ≤ N ≤ 1440.)

Per-table column selection — text fallback (column lists are too varied for multi-choice):

"For <table>, type column changes one per line: exclude <column> to drop a column from sync include <column> to add one that's currently excluded all to reset to every column from the manifest skip to leave columns unchanged"

Validate every named column exists in .datamodel-manifest.json; reject typos with the closest-match column suggestion.

Step 3.5e — Re-confirm

After all picked sub-flows complete, re-render the summary (Step 3.5a format) with the changed rows marked → updated in a different colour or with a leading *. Then re-run Step 3.5b — same three-option AskUserQuestion. The user can adjust again, accept, or cancel.

This loop is bounded by user patience, not a hard limit. If they pick "Adjust" repeatedly without ever choosing "Accept" or "Cancel", that's their prerogative — every loop is reversible and nothing has hit Dataverse yet.

Step 3.5f — Memory bank checkpoint (after Accept and publish)

## Offline profile
status: in-progress
profileName: <name>
mode: create-new | extend
configReview: accepted

Design rationale. The original Step 3.5 used free-text replies ("type accept or describe edits in English") to keep things conversational. In practice users typed responses the regex parsers didn't recognise — change scope of contact to teamonly, set sync to 10, etc. — and the skill either silently dropped the edit or asked a clarifying question that drove additional confusion. The AskUserQuestion flow above eliminates parsing risk for the enumerable fields (scope, sync interval, top-level decision) while preserving the free-text path for the genuinely free-form fields (name, description, column lists). Net result: zero ambiguous interactions for the common adjustments, fewer typing-induced errors, parity with /create-mobile-app's plan-gate UX.

Step 4 — Run the internal enable-tables-offline workflow if needed

Telemetry checkpoint: enable_dataverse_tables_offline

If Gate 1 identified any table needing change, read and execute ${PLUGIN_ROOT}/skills/enable-tables-offline/SKILL.md with the approved table list and the complete scoped handoff below. Configuration review must already be accepted; neither a saved manifest nor a bare table list is approval.

$ARGUMENTS: --working-dir '<working_dir>' <comma-separated approved logical names>
 
Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: setup-offline-profile
  working_dir: <working_dir>
  phase: implementation
  approved_scope:
    environmentId: <selected-environment-id>
    environmentUrl: <envUrl>
    tenantId: <tenantId>
    tables: <exact Gate 1-approved prerequisite table allowlist>
    operations: <approved IsAvailableOffline/ChangeTrackingEnabled changes>
    publication: <approved targeted publication; broader fallback only if separately approved>
  supplied_answers: <current offline gate responses>

Wait for it to return and parse its literal first-line status. DONE continues; DONE_WITH_CONCERNS must be surfaced before continuing. On NEEDS_CONTEXT, resolve the missing context within this owner's approved root/scope or return the blocker; never re-dispatch with a different app or infer approval.

If BLOCKED, propagate the block up — STOP.

If all tables were already enabled, skip this step.

Step 5 — POST profile shell

Telemetry checkpoint: create_offline_profile_shell

Print before starting:

"→ Creating MobileOfflineProfile record (Name + Description only)…"

For create-new mode:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "mobileofflineprofiles" \
  --tenant-id "<tenantId>" \
  --body '{
    "name": "<app name> Offline Profile",
    "description": "<auto-generated description referencing app name + scope summary>"
  }' \
  --include-headers

Capture mobileofflineprofileid from the OData-EntityId response header (matches the pattern in /add-dataverse Step 5b).

For extend mode: re-use the existing mobileofflineprofileid from Step 2.

Write to memory-bank.md:

## Offline profile
status: in-progress
profileId: <guid>
profileName: <name>
mode: create-new | extend
gate1: approved

(Gate 2 — REMOVED, consolidated into Step 3.5)

Step 6 — POST profile items

Telemetry checkpoint: add_tables_to_offline_profile

Print before starting:

"→ Creating MobileOfflineProfileItem records (one per table, sequential)…"

⚠️ Concurrency rule. Profile items reference each other implicitly via the parent profile. Issue POSTs sequentially, one at a time. The mobileofflineprofileitem entity does NOT hold the metadata lock that EntityMetadata does, but the validation pass on each POST reads neighboring items — parallel POSTs occasionally return 412 PreconditionFailed. Sequential is the safe path.

For each table, in sequence:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "mobileofflineprofileitems" \
  --tenant-id "<tenantId>" \
  --body '{
    "name": "<table display name>",
    "regardingobjectid@odata.bind": "/mobileofflineprofiles(<profileId>)",
    "selectedentitytypecode": "<table-logicalname>",
    "recorddistributioncriteria": <0|1|2>,
    "recordsownedbyme": <bool>,
    "recordsownedbymyteam": <bool>,
    "recordsownedbymybusinessunit": <bool>,
    "getrelatedentityrecords": true,
    "syncintervalinminutes": 10
  }' \
  --include-headers

Capture each mobileofflineprofileitemid from the response header. Store in a local map tableLogicalName → itemId — needed for Step 7 (associations) and Step 9 (offline-profile.json).

selectedcolumns is NOT set here — added at Gate 3 / Step 7 once the user confirms the column subset.

Print ✓ <table> after each 2xx.

(Gate 3 — REMOVED, consolidated into Step 3.5)

Step 7 — POST associations + PATCH selectedcolumns

Telemetry checkpoint: configure_offline_profile_associations

Print before starting:

"→ Creating association rows + PATCHing selectedcolumns on each profile item…"

Step 7a — POST mobileofflineprofileitemassociation rows

Empirical 2026-05-24 + 2026-05-25 capture from maker portal unblocked association creation. Recipe (no selectedrelationshipsschema field — server fills it):

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "mobileofflineprofileitemassociations" \
  --tenant-id "<tenantId>" \
  --body '{
    "name": "<relationshipSchemaName>",
    "relationshipdisplayname": "<relationshipSchemaName>",
    "relationshipid": "<MetadataId-of-1:N-relationship-from-architect>",
    "regardingobjectid@odata.bind": "/mobileofflineprofileitems(<PARENT-item-id>)"
  }' \
  --include-headers

⚠️ Critical direction rule. regardingobjectid is the parent (1-side) profile item. For an account → orderline 1:N relationship, the association lives on the account profile item with the relationship account_orderline (read from EntityDefinitions(LogicalName='account')/OneToManyRelationships). POSTing on the orderline (child) side fails PublishXml with 0x80071140 — no relationships are specified for this Related-only table. This is the canonical bug — architect's Step 5 now explicitly walks parents' OneToManyRelationships to produce parent-keyed output.

For each (PARENT-item, 1:N-relationship-to-child) pair from the architect's proposal:

1. Resolve relationshipid (MetadataId GUID) via EntityDefinitions(LogicalName='<PARENT-table>')/OneToManyRelationships filtering by SchemaName === <relationshipSchemaName>. Cache the lookup per parent table.
2. POST the association (sequential — parallel POSTs occasionally return 412 PreconditionFailed).
3. Capture the new mobileofflineprofileitemassociationid from the OData-EntityId response header.

Skip-when-redundant rule. If the parent profile item has recorddistributioncriteria=1 (All records), the architect should have pruned associations on it (per Step 5 pruning rule). Defensively: if any propagate through, SKIP them at POST time. Print: ↷ Skipping <association> on All-records parent <table> — redundant, all rows download anyway.

Pre-publish cycle detection. Before Step 8 publish, build the relationship graph from the just-created associations and DFS for cycles. If a cycle exists (e.g. account → task → account), prompt the user to remove ONE association and re-do this step for the affected pair — otherwise Step 8 will return 0x80071141. See shared/references/dataverse-offline-api.md §6b.

Idempotency. Re-POSTing an existing (item, relationship) pair returns 409 Conflict; the dataverse-request.js looksLikeDuplicate rescue treats this as success. Re-runs after a partial failure are safe.

Skip Step 7a entirely if the architect's proposal includes zero relationships (rare — usually fixture-grade single-table profiles).

Step 7b — PATCH selectedcolumns on each item

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> PATCH \
  "mobileofflineprofileitems(<itemId>)" \
  --tenant-id "<tenantId>" \
  --body '{
    "selectedcolumns": "<JSON string — see below>"
  }'

selectedcolumns shape (verified by inspecting an existing profile created by maker portal — see §10 known blocker in plan for caveat):

{
  "Columns": ["cr123_title","cr123_body","cr123_visitid","modifiedon","createdon","statecode"]
}

Wrap as a stringified JSON in the memo field.

If syncintervalinminutes was edited at Gate 3, include it in the same PATCH.

Step 8 — Publish

Telemetry checkpoint: publish_offline_profile

Print before starting:

"→ Publishing profile (targeted PublishXml)…"

Validate step intentionally skipped. Empirical 2026-05-17: the Validate action's documented body shape is rejected by the server. The maker portal does NOT call Validate either (confirmed via 2026-05-24 capture) — publish-time validation runs server-side as part of PublishXml. isvalidated=true is set by the publish call itself, not by a separate Validate.

Targeted PublishXml — the maker portal's pattern (empirical 2026-05-24):

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "PublishXml" --tenant-id "<tenantId>" --body '{
    "ParameterXml": "<publish><mobileofflineprofiles><mobileofflineprofile><profileId></mobileofflineprofile></mobileofflineprofiles></publish>"
  }'

Publishes ONLY this profile, not the entire org's customizations. Empirically much faster + less rate-limit-prone than PublishAllXml on shared envs.

For the repair helpers below, use the reconciliation reference's Scoped helper handoffs with orchestrator: setup-offline-profile, the same absolute working_dir, selected environment/tenant/profile, and the exact user-approved repair scope. Pass --working-dir '<working_dir>' and the selected profile/table arguments. Do not infer a new repair approval from the original profile-creation approval.

On 400 / 0x80071141 "circular relationship": the profile's association graph has a cycle (e.g. account → task → account). Parse the path from the error message, prompt the user to drop ONE of the offending associations, re-DELETE that association row via DELETE /mobileofflineprofileitemassociations(<id>), then re-attempt publish. See shared/references/dataverse-offline-api.md §6b.

On 400 / 0x80071140 "no relationships are specified" for a Related-only table: a profile item has recorddistributioncriteria=0 but no associations point at it. Parse the table name from the error message and prompt the user with two choices:

1. /add-table-to-offline-profile --table <name> --add-associations — re-runs the architect for relationship discovery, POSTs missing associations.
2. /edit-offline-profile --table <name> --scope 2 --me — changes scope to Organization rows + User's rows (the architect's fallback).

For fresh /setup-offline-profile runs this error should never fire because Step 7a POSTs associations before Step 8 publish. But it CAN fire on retrofit scenarios where a profile published under v0.1's old "no associations" recipe is later edited — Dataverse's publish-validator appears to compare against the previously-published snapshot, not the current uncommitted state. Empirically observed 2026-05-24 on chanel-rm.

Fallback — PublishAllXml: only if targeted publication cannot complete and the user separately approves publishing all pending environment customizations. A profile-scoped approval, timeout, or rate limit is not broader publication consent. Otherwise report the failure without widening scope.

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> POST \
  "PublishAllXml" --tenant-id "<tenantId>" --body '{}'

Handle the timeout-but-success pattern — empirically observed on shared envs (CRM527116 + chanel-rm demos): PublishAllXml triggers a 4-retry 429 backoff, dataverse-request.js times out client-side after ~2 min, but the publish DID commit server-side. The targeted PublishXml should avoid this in most cases, but the fallback path still needs to handle it.

Protocol after the POST call returns:

1. If status 204 → publish succeeded, continue.

2. If status 0 AND error contains Request timed out OR 429 rate-limited → DO NOT treat as failure. Run the verification GET below:

   cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
   node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET \
     "mobileofflineprofiles(<profileId>)?\$select=componentstate,publishedon" --tenant-id "<tenantId>"
   • componentstate == 0 AND publishedon is a non-null ISO8601 timestamp within the last 5 minutes → treat as success. Print: ↷ PublishAllXml client timed out but committed server-side (componentstate=0, publishedon=<ts>). Continue.
   • componentstate == 1 (Unpublished) → publish genuinely didn't land. Retry once with a 30s pre-wait (let any in-flight env publishes drain). On second failure, return DONE_WITH_CONCERNS: publish timed out twice; profile saved but unpublished — re-run /setup-offline-profile or PublishAllXml manually.

3. If status is any other non-204 → return BLOCKED: publish failed with <status>.

After confirmed success, re-GET the profile and check publishedon for the artifacts step.

Step 9 — Persist artifacts

Telemetry checkpoint: persist_offline_profile_snapshot

Print before starting:

"→ Writing offline-profile.json + memory-bank.md…"

Important: this skill must NOT modify power.config.json. That file is owned by pa app init and its schema is controlled by the upstream tool — adding custom fields there risks being overwritten on re-init and breaks when the upstream schema changes. All app-level offline config goes into offline-profile.json (which we own) under an appConfig block.

9a — Write offline-profile.json to the project root. Canonical schema (must match scripts/verify-offline-profile.js's expectations; the script compares associations by relationshipId):

{
  "profileId": "<guid>",
  "name": "<name>",
  "publishedOn": "<iso8601>",
  "mode": "create-new | extend",
  "appConfig": {
    "enabled": true,
    "serverRowLimit": 2000,
    "/* BEGIN OFFLINE-CONFIG-WORKAROUND */": "remove when SDK gaps are fixed upstream — tracked in microsoft/power-platform-skills/plugins/mobile-apps/template#main (instanceUrl) + PowerApps-Client (useDda + entitiesIncluded). Bracket exists so the future cleanup diff is mechanical.",
    "useDda": false,
    "entitiesIncluded": ["<logicalName-1>", "<logicalName-2>", "..."],
    "instanceUrl": "<envUrl>",
    "/* END OFFLINE-CONFIG-WORKAROUND */": ""
  },
  "tables": [
    {
      "logicalName": "cr123_order",
      "itemId": "<guid>",
      "recordDistributionCriteria": 2,
      "recordsOwnedByMe": true,
      "recordsOwnedByMyTeam": false,
      "recordsOwnedByMyBusinessUnit": false,
      "syncIntervalInMinutes": 10,
      "selectedColumns": ["cr123_ordernumber", "cr123_total", "..."],
      "schemaColumns": ["cr123_ordernumber", "cr123_total", "cr123_notes", "..."],
      "relationships": [
        {
          "schemaName": "cr123_order_cr123_orderline",
          "relationshipId": "<MetadataId-guid-of-the-1:N-relationship>",
          "targetEntity": "cr123_orderline",
          "associationId": "<mobileofflineprofileitemassociationid-guid>"
        }
      ]
    }
  ]
}

Schema invariants (enforced by the verify script):

• profileId is the source of truth for the published mobileofflineprofileid — runtime + /edit-offline-profile + /assign-offline-profile read it from here. Do NOT also write it to power.config.json.
• appConfig carries every app-level offline setting the runtime consumes at boot. The three OFFLINE-CONFIG-WORKAROUND-bracketed fields are temporary and tracked for upstream removal — keep them contiguous so a future git diff showing the cleanup is scoped to that block.
• relationships[] lives on the PARENT table entry (the table on the 1-side of the 1:N relationship). Pure-child tables (e.g. cr123_orderline) have empty relationships: [].
• Each relationships[] entry has schemaName (the relationship's SchemaName from EntityDefinitions metadata), relationshipId (the relationship's MetadataId GUID — this is the canonical comparison key, stable across server-side relationshipname formatting), targetEntity (child entity logical name), and associationId (the created mobileofflineprofileitemassociationid).
• recordDistributionCriteria=1 (All records) parents always have relationships: [] — associations would be redundant (see architect Step 5 pruning rule).
• schemaColumns[] is the schema-reconciliation baseline — the full set of the table's schema column logical names (from .datamodel-manifest.json) that existed when this item was created. It is NOT the same as selectedColumns (which is a curated subset the runtime syncs): schemaColumns records everything the schema had at reconciliation time, including columns deliberately left out of selectedColumns. scripts/offline-profile-delta.js compares later manifest columns against this baseline to detect genuinely new schema columns (manifest.columns − schemaColumns) without false-flagging deliberate exclusions. Populate it from the manifest entry for each table; if the manifest lists no columns for a reused table, write []. See offline-profile-reconciliation.md.
• JSON doesn't support comments — the /* BEGIN/END OFFLINE-CONFIG-WORKAROUND */ keys above are illustrative bracketing for the SKILL author. Do NOT write those literal keys to offline-profile.json. When the skill actually patches the file, emit only the real fields (useDda, entitiesIncluded, instanceUrl) inside appConfig and keep them contiguous.

Example node script (writes the file in one shot — no read-modify-write against power.config.json):

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node -e '
  const fs = require("fs");
 
  // Genuine app-level offline config (always written)
  const appConfig = {
    enabled: true,
    serverRowLimit: 2000,
  };
 
  // BEGIN OFFLINE-CONFIG-WORKAROUND (remove when underlying SDK gaps are fixed
  // upstream — tracked separately in plugins/mobile-apps/template and PowerApps-Client).
  appConfig.useDda = false;
  appConfig.entitiesIncluded = [/* logicalName for each table in the profile */];
  appConfig.instanceUrl = "<envUrl>";
  // END OFFLINE-CONFIG-WORKAROUND
 
  const profile = {
    profileId: "<guid-from-step-5>",
    name: "<name>",
    publishedOn: "<iso8601>",
    mode: "create-new", // or "extend"
    appConfig,
    tables: [/* one entry per profile item — see schema above */],
  };
 
  fs.writeFileSync("offline-profile.json", JSON.stringify(profile, null, 2) + "\n");
'

Field rationale:

Do NOT touch power.config.json from this skill. Earlier drafts wrote the same fields into power.config.json.offline.* and databaseReferences[*].databaseDetails.linkedEnvironmentMetadata.instanceUrl. That was reverted because power.config.json is generated by pa app init, whose schema we don't control — adding custom fields there means re-init can wipe them and upstream schema changes can break this skill. If you find a code path here that still mutates power.config.json, treat it as a bug.

9c — Update memory-bank.md ## Offline profile:

status: done
profileId: <guid>
profileName: <name>
mode: create-new | extend
publishedOn: <iso8601>
gate1: approved
gate2: approved
gate3: approved
tablesCount: <N>
associationsCount: <M>

9d — Append a ## Offline Profile section to native-app-plan.md summarizing the final state (mirrors the data-model section pattern).

Step 9.5 — Verify

Telemetry checkpoint: verify_published_offline_profile

Print before starting:

"→ Verifying the on-server profile matches offline-profile.json…"

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/verify-offline-profile.js" <envUrl> \
  --project-root '<working_dir>' --tenant-id "<tenantId>"

Read the JSON output:

The verify script is also the canonical implementation behind /preview-offline-scope (v0.2) — keeping it as a step here means it's exercised on every fresh creation.

Step 10 — Summary

Print:

✓ Mobile Offline Profile created.
 
  Profile name : <name>
  Profile ID   : <guid>
  Tables       : <N> (<M> required prereq enablement)
  Relationships: <K> associations
  Published    : <iso8601>
 
Saved to project:
  - offline-profile.json  (profile metadata + appConfig + tables)
  - memory-bank.md        (## Offline profile section)
  - native-app-plan.md    (## Offline Profile section)
 
Note: power.config.json was NOT modified (owned by pa app init).
 
Next steps:
  - /assign-offline-profile        → assign users / teams to this profile (not yet implemented — v0.3)
  - /preview-offline-scope         → estimate download size before pushing the app (not yet implemented — v0.2)
  - /edit-offline-profile <table>  → re-scope one table (not yet implemented — v0.2)
 
Runtime: The template 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 configures
that runtime; it does not scaffold a second app-owned store, queue, or sync engine.

Status code (final line)

• DONE — profile created and published, artifacts written
• DONE_WITH_CONCERNS: <list> — created but with caveats (validate skipped, some columns flagged, some tables uncustomizable)
• NEEDS_CONTEXT: <missing> — data model missing, env URL unresolvable, etc.
• BLOCKED: <reason> — auth failed, PrivilegeCheckFailed, env URL unreachable, or sub-skill /enable-tables-offline returned BLOCKED

Failure recovery

Every step writes a checkpoint to memory-bank.md. On failure mid-flow:

Never leave a profile half-committed in memory-bank.md with status: in-progress past a session — the next session's Step 1b will prompt to resume or delete it.