feat(mobile-apps): emit skill-started telemetry from plugin hooks

Wires the Mobile Apps plugin into the vendored 1DS telemetry library so we
can see which mobile skills developers actually run.

- Register two hooks: PreToolUse(Skill) for agent-invoked skills and
  UserPromptSubmit for manual slash commands, which Copilot pre-expands
  into <skill-context> and never reports as a Skill tool call.
- Add mobile-telemetry.js, the plugin adapter that gates on a provisioned
  ikey, resolves the session, and builds the skill-started event.
- Correlate nested Copilot agents, which receive a transient call_* session
  id, back to their owning UUID session via a bounded tail read of the local
  session-state log, cached as a short-lived alias file. Fails open.
- Discover tracked skills from the skills directory instead of hardcoding.
- Add the telemetry skill so users can inspect or opt out.
- Add script tests plus a CI workflow that sets the plugin opt-out env var
  so test runs never post to the production collector.

Author: Nikhil Agrawal

.github/workflows/mobile-apps-script-tests.yml

@@ -0,0 +1,39 @@
+# Mobile Apps telemetry is exercised with isolated configs and local mirrors.
+# The job-level opt-out is a backstop against accidental production emission if
+# the plugin is provisioned later and a new test forgets its local test seam.
+name: mobile-apps-script-tests
+
+on:
+    pull_request:
+        branches:
+            - main
+        paths:
+            - "plugins/mobile-apps/**"
+            - "shared/telemetry/**"
+
+jobs:
+    test-mobile-apps-scripts:
+        name: test-mobile-apps-scripts (${{ matrix.os }})
+        runs-on: ${{ matrix.os }}
+        env:
+            POWER_PLATFORM_SKILLS_TELEMETRY_MOBILE_APP_OPTOUT: "1"
+        strategy:
+            fail-fast: false
+            matrix:
+                os:
+                    - ubuntu-latest
+                    - windows-latest
+                    - macos-latest
+        steps:
+            - name: checkout
+              uses: actions/checkout@v4
+
+            - name: setup-node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+
+            - name: run-mobile-apps-script-tests
+              shell: bash
+              working-directory: plugins/mobile-apps/scripts/tests
+              run: node --test

plugins/mobile-apps/AGENTS.md

@@ -2,7 +2,7 @@
 
 This file provides guidance to AI Agents when working with the **mobile-app** plugin.
 
-> **Status:** v0 — 23 skills + 5 agents authored. The latest Expo standalone template snapshot is bundled under `template/`. Read [README.md](./README.md) for the command list.
+> **Status:** v0 — 24 skills + 5 agents authored. The latest Expo standalone template snapshot is bundled under `template/`. Read [README.md](./README.md) for the command list.
 
 ## What This Plugin Is
 
@@ -26,8 +26,8 @@ README.md                      ← Plugin overview
 agents/                        ← native-app-planner, data-model-architect, screen-planner, screen-builder
 shared/                        ← shared-instructions, references, samples, memory-bank template
 skills/                        ← /create-mobile-app, /add-dataverse, /add-connector, /add-native, ...
-scripts/                       ← shared helpers, including validate-mobile-files.js for skill-owned changed-file validation
-hooks/                         ← Validator implementations invoked explicitly by mobile workflows
+scripts/                       ← shared helpers, including validate-mobile-files.js and bundled telemetry
+hooks/                         ← Telemetry start hooks plus validators invoked explicitly by mobile workflows
 ```
 
 ## Template source
@@ -56,7 +56,7 @@ Do not add preparation rewrites for `scheme`, `package`, `bundleIdentifier`, `sr
 7. **Persisted plan** — Write `native-app-plan.md` (Mermaid ER + per-screen specs + native capabilities matrix) as the source of truth that sub-skills `Read`.
 8. **CLI compatibility** — Use `npx power-apps ...` for code-app lifecycle and data-source commands. Use `scripts/resolve-environment.js` plus `az` tokens for Dataverse environment URL/tenant discovery and Azure/Entra operations. See [`shared/shared-instructions.md`](./shared/shared-instructions.md).
 9. **Agent invocation namespace** — All `Task` invocations of agents in this plugin MUST use the fully-qualified `mobile-app:<agent-name>` form (e.g. `mobile-app:native-app-planner`, `mobile-app:screen-builder`). Bare names like `native-app-planner` return `Agent type 'native-app-planner' not found` because Claude Code namespaces all plugin agents by plugin name.
-10. **Plugin isolation** — Do not add `hooks/hooks.json`: Claude loads plugin hooks during unrelated workflows, so a mobile write hook can block Canvas Apps tool calls. Mutating skills follow the changed-file gate in `shared/shared-instructions.md`, and final-artifact agents invoke `scripts/validate-mobile-files.js` directly.
+10. **Plugin isolation** — `hooks/hooks.json` is limited to fail-open telemetry start hooks. They never validate, mutate, or block tool calls. Do not add write/validation hooks: mutating skills follow the changed-file gate in `shared/shared-instructions.md`, and final-artifact agents invoke `scripts/validate-mobile-files.js` directly.
 11. **Invocation metadata** — Public entry skills use `user-invocable: true` and remain model-invocable. Bundled implementation helpers use both `user-invocable: false` and `disable-model-invocation: true`; their owner reads `SKILL.md` directly. Hidden standalone workflows such as `assign-offline-profile` and `preview-offline-scope` use `user-invocable: false` without disabling model invocation because no owner reads them directly. Agents use `user-invocable: false` without `disable-model-invocation` so qualified `Task` delegation remains available.
 12. **Sub-agent return-status protocol** — Every agent in this plugin (`native-app-planner`, `data-model-architect`, `screen-planner`, `screen-builder`) MUST return a status code as the **literal first line** of its final message. Orchestrators (skills that invoke agents via `Task`) MUST parse the first line and branch:
 
@@ -74,6 +74,17 @@ Do not add preparation rewrites for `scheme`, `package`, `bundleIdentifier`, `sr
     - Special early-return signals (`INDUSTRY_CONFIRM_REQUESTED:`, `DESIGN_VIBE_REQUESTED:`) pre-date this protocol and remain in effect — they are special-cased "ask the user one question and re-spawn me" handoffs, not terminal returns.
     - The canonical orchestrator handler lives in [`skills/create-mobile-app/SKILL.md`](./skills/create-mobile-app/SKILL.md) Step 3.0. Future skills that spawn agents should reference it rather than duplicating the switch.
 
+## Telemetry
+
+Mobile Apps bundles the canonical stdlib-only 1DS transport from the repo-root `shared/telemetry/lib` at `scripts/lib/telemetry/lib`. Edit the shared source first, then refresh this physical copy in the same change; never copy another plugin's `ikey.json` or resolver.
+
+- **Start-only lifecycle:** `UserPromptSubmit` records explicit slash-command starts and `PreToolUse(Skill)` records programmatic Skill-tool starts; both may fire for one visible slash command. `UserPromptSubmit` payloads differ by host — Claude Code passes the raw `/mobile-app:<skill>` text, Copilot CLI pre-expands it to a `<skill-context name="<skill>">` wrapper and emits no Skill pre-tool event — so both shapes must stay recognized or manual runs go uncaptured. Do not add `skill_completed`, duration, outcome, or persisted correlation state: Power Pages deliberately removed that flow because the hook boundary does not prove the workflow completed.
+- **Coverage and attribution:** `scripts/lib/mobileapp-hook-utils.js` discovers every user- or model-invocable top-level skill, including `telemetry`. Direct-read helpers with `disable-model-invocation: true` are not independently invoked and are excluded. Bare and `mobile-app:`-qualified names are both attributed; explicitly foreign plugin namespaces are excluded.
+- **Session correlation:** Stable host session ids pass through unchanged. Copilot CLI reports a transient `call_*` id to nested-agent hooks, so `resolveCopilotRootSessionId` in `scripts/lib/mobile-telemetry.js` resolves it to the unique recent UUID session whose local `~/.copilot/session-state/<uuid>/events.jsonl` structurally owns that `agentId`, reading only a bounded tail. Keep host-specific quirks contained in that one function. The verified root is cached as one atomic 30-minute alias file per hashed call id so fresh hook processes reuse it; aliases hold no prompts, cwd, or tool arguments and are never transmitted. Missing, stale, malformed, or ambiguous state fails open to the original id, and Claude Code and Codex ids are not rewritten.
+- **Privacy:** Mobile Apps sends no prompt, tool input, cwd, path, URL, credential, username, hostname, Dataverse org/tenant ID, or Entra object ID. The dynamic `eventInfo` contains only `invocationSource` (`prompt` or `pretool`).
+- **Controls:** `scripts/lib/telemetry/ikey.json` remains `disabled: true` with a Mobile-specific placeholder until its own 1DS key, collector, stream annotation, and Kusto mapping are provisioned. That is a true hard-off: no local log and no POST. Once enabled, `/mobile-app:telemetry off` and `POWER_PLATFORM_SKILLS_TELEMETRY_MOBILE_APP_OPTOUT=1` suppress transmission while preserving the local diagnostic mirror.
+- **CI:** Every Mobile Apps test job must set `POWER_PLATFORM_SKILLS_TELEMETRY_MOBILE_APP_OPTOUT=1`. The single positive wire test clears that backstop only in its child process and routes the event to `POWER_PLATFORM_SKILLS_FAKE_HTTPS`; all other positive tests remain opted out and exercise the local mirror.
+
 ## Decisions made
 
 - ✅ Markdown plan with Mermaid (no HTML rendering)

plugins/mobile-apps/README.md

@@ -216,6 +216,7 @@ Example edit flows:
 | `/deploy` | ✅ v0 | Build + push — `npm run build` then `npx power-apps push` to the env in `power.config.json`. **Does not** drive `expo run:ios` or `expo run:android` (out of scope for v0). |
 | `/open-wrap-url` | ✅ v0 | Opens the Wrap URL in browser for an app ID using `https://make.powerapps.com/environments/<envID>/wrap?appID=<appID>`. Requires both `--app-id` and `--env-id`. |
 | `/report-issue` | ✅ v0 | Read-only diagnostic — collects env / Expo / Node versions, project context, recent errors, and renders a copy-paste-ready GitHub issue body. Sanitizes secrets. |
+| `/telemetry` | ✅ v0 | Enable, disable, or show the per-user Mobile Apps telemetry transmission preference. |
 | `/design-system` | ✅ v0 | End-to-end design system — collects brand inputs (logo, brand doc, website, free text, canvas app, code app, Figma), runs a 3-style visual picker, writes `brand/design-system.md` + `brand/tokens.ts`, renders branded screen previews. Auto-invoked at Step 6.75 of `/create-mobile-app`; also standalone. |
 | `/preview-screens` | ✅ v0 | Renders generated TSX screens as a browser-viewable HTML preview (no Metro needed). Uses Tamagui → HTML mapping. |
 | `/add-datasource` | ✅ v0 | Alias for `/add-connector` — discoverable name for "how do I connect to X?" |
@@ -237,6 +238,24 @@ Example edit flows:
 | `screen-builder` | Mutation — writes ONE TSX file per assigned screen, runs N in parallel |
 | `offline-profile-architect` | Read-only — proposes per-table row scope, relationships, selected columns, sync frequency; returns `_offline_section.md` for `/setup-offline-profile` to embed in `native-app-plan.md` |
 
+## Telemetry and privacy
+
+The Mobile Apps plugin includes start-only usage telemetry built on the same shared 1DS transport as Power Pages. The checked-in Mobile Apps configuration is currently `disabled: true` with a placeholder key, so it is hard-off until a dedicated Mobile Apps stream and instrumentation key are provisioned. While hard-off, it performs no telemetry shellouts, writes no local event log, and sends nothing.
+
+Once provisioned, a start event can include the skill name, plugin version, session and per-start correlation IDs, OS/Node versions, AI-agent name/version, and whether the host observed the start through `UserPromptSubmit` or `PreToolUse(Skill)`. It never includes prompts, skill arguments, tool inputs, file paths, cwd, app/site names, URLs, credentials, usernames, hostnames, Dataverse organization or tenant IDs, or Entra object IDs.
+
+Both host surfaces are covered — an explicit slash command and a programmatic Skill-tool call — so some hosts may produce two `skill_started` records for one visible run. The plugin does not emit `skill_completed`, success/failure, error, or duration data because the available hook boundary does not prove that the workflow itself completed.
+
+Control the per-user transmission preference with:
+
+```text
+/mobile-app:telemetry status
+/mobile-app:telemetry off
+/mobile-app:telemetry on
+```
+
+After provisioning, `off` stops network transmission but retains the sanitized local diagnostic mirror under `~/.power-platform-skills/telemetry/mobile-app/sessions/<sessionId>/events.jsonl`. Automation can force transmission off with `POWER_PLATFORM_SKILLS_TELEMETRY_MOBILE_APP_OPTOUT=1`; this overrides the saved preference and `on`.
+
 ## Known blockers
 
 ## See also

plugins/mobile-apps/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "_comment": "Telemetry-only start hooks. They never validate, mutate, or block tool calls. File validation stays owned by each workflow through scripts/validate-mobile-files.js.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Skill|skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const path=require('node:path'); const root=process.env.PLUGIN_ROOT||process.env.CLAUDE_PLUGIN_ROOT; if(!root)process.exit(0); try{require(path.resolve(root,'hooks','run-telemetry.js')).start('pretool');}catch{}\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const path=require('node:path'); const root=process.env.PLUGIN_ROOT||process.env.CLAUDE_PLUGIN_ROOT; if(!root)process.exit(0); try{require(path.resolve(root,'hooks','run-telemetry.js')).start('prompt');}catch{}\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/mobile-apps/hooks/run-telemetry.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+let telemetry;
+let getTrackedSkillFromPrompt;
+let getTrackedSkillFromToolInput;
+try {
+  telemetry = require('../scripts/lib/mobile-telemetry');
+  ({
+    getTrackedSkillFromPrompt,
+    getTrackedSkillFromToolInput,
+  } = require('../scripts/lib/mobileapp-hook-utils'));
+} catch {
+  process.exit(0);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+    process.stdin.on('error', () => resolve(input));
+  });
+}
+
+function invocationFor(mode, payload) {
+  if (mode === 'prompt') return getTrackedSkillFromPrompt(payload.prompt);
+  if (mode === 'pretool') return getTrackedSkillFromToolInput(payload.tool_input);
+  return null;
+}
+
+async function run(mode) {
+  let payload;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    return;
+  }
+
+  const skillName = invocationFor(mode, payload);
+  if (!skillName) return;
+
+  const context = telemetry.createTelemetryContext(payload);
+  if (context) telemetry.emitSkillStarted(context, { skillName, source: mode });
+}
+
+function start(mode) {
+  run(mode).catch(() => {}).finally(() => process.exit(0));
+}
+
+if (require.main === module) start(process.argv[2]);
+
+module.exports = { start };