Per-plugin telemetry env-var toggle + enable power-pages transmission (#195)

* feat(telemetry): add per-plugin env-var name + value reader

Adds `telemetryEnvVarName` and `readTelemetryEnvChoice` to shared/telemetry/lib/user-config.js so automation/CI can toggle telemetry via POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN> without the slash skill. Injectable `env` param keeps tests hermetic.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(telemetry): resolve opt-out by config-wins-then-env precedence

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(telemetry): cover env-var transmission gate + config-wins in dispatcher

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(telemetry): status CLI reports effective state, honoring env override

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(telemetry): isolate per-plugin env var in CLI test harness

* docs(telemetry): document per-plugin env-var opt-out + config-wins precedence

* telemetry(power-pages): enable transmission (ikey.json disabled:false)

Flips the repo-side kill switch off so power-pages 1DS telemetry transmits
to the resolved regional collector. Overrides the default-ship-disabled
posture per explicit maintainer instruction.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* telemetry: switch env toggle to dotnet-style _OPTOUT with highest precedence

Per PR #195 review (priyanshu92): rename the per-plugin env var to
POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT (power-pages:
POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT). It is a dotnet-style
opt-out boolean (1/true disables) and now has the HIGHEST precedence —
overriding both a persisted config.json choice and /telemetry on. The env var
only disables; it never re-enables.

- user-config.js: telemetryOptOutEnvVarName + readTelemetryEnvOptOut replace the
  on/off env reader; effectiveTelemetryChoice short-circuits to "off" on opt-out.
- Tests rewritten for opt-out semantics + env-wins precedence; user-config test
  harness wraps isTransmissionOptedOut to default env={} so CI vars can't leak
  (Copilot review).
- Docs updated across README/AGENTS/workflow; fixed <plugin> -> <PLUGIN> casing
  and reconciled the ikey.json disabled posture (now disabled:false) per review.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(telemetry): clarify behavior of 'off' command regarding local logs

---------

Co-authored-by: Amit Joshi <amitjoshi@microsoft.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

AGENTS.md

@@ -69,7 +69,7 @@ This keeps the skill discoverable in each plugin while preserving install-time p
 
 Edit `shared/telemetry/` directly — the symlink makes changes live for every adopting plugin immediately; there is nothing to re-sync.
 
-Per-plugin iKey/collector routing is pluggable via a `resolver.js` placed next to the plugin's `ikey.json` (implementing the `resolve`/`isProvisioned` contract); the shared library ships only that contract plus a static-key fallback, not any routing logic.
+Per-plugin iKey/collector routing is pluggable via a `resolver.js` placed next to the plugin's `ikey.json` (implementing the `resolve`/`isProvisioned` contract); the shared library ships only that contract plus a static-key fallback, not any routing logic. A per-plugin opt-out env var `POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT` (derived as the uppercased plugin name with non-alphanumerics collapsed to `_`, suffixed `_OPTOUT`) disables transmission for automation when set to `1`/`true` (dotnet `*_TELEMETRY_OPTOUT` convention); it has the **highest precedence**, overriding both the persisted `config.json` choice and `/<plugin>:telemetry on`.
 
 Current adopters: `power-pages`. Others adopt on demand.
 

README.md

@@ -214,4 +214,4 @@ Any use of third-party trademarks or logos are subject to those third-party's po
 
 ## Telemetry
 
-Plugins that ship 1DS telemetry (currently: `power-pages`) gather anonymous usage signals. Telemetry is default-on; users opt out per-plugin via the `/<plugin>:telemetry off` command (e.g. `/power-pages:telemetry off`), stored in `~/.power-platform-skills/config.json`. See `shared/telemetry/README.md` for what is sent.
+Plugins that ship 1DS telemetry (currently: `power-pages`) gather anonymous usage signals. Telemetry is default-on; users opt out per-plugin via the `/<plugin>:telemetry off` command (e.g. `/power-pages:telemetry off`), stored in `~/.power-platform-skills/config.json`. For automation/CI, each adopting plugin also honors a per-plugin opt-out environment variable `POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT` (e.g. `POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1`); when set it disables transmission with the highest precedence, overriding any `/<plugin>:telemetry` choice. See `shared/telemetry/README.md`.

plugins/power-pages/AGENTS.md

@@ -407,9 +407,9 @@ These patterns have caused repeated PR review feedback. Check for them before su
 
 This plugin ships 1DS telemetry for skill-run and script-run signals. The shared library lives at the repo-root `shared/telemetry/`; `scripts/lib/telemetry/lib` is a **symlink** to `shared/telemetry/lib`, so the shared code is the live code. Zero npm dependencies — nothing to install.
 
-- **`scripts/lib/telemetry/lib` is a symlink** to the repo-root `shared/telemetry/lib` — edit `shared/telemetry/lib/` directly; there is no copy to re-sync. The real files under `scripts/lib/telemetry/` are `ikey.json` (this plugin's config) and `resolver.js` (the resolver contract implementation). **Posture:** the committed `ikey.json` ships `disabled: true`; a working-tree `disabled: false` is a local experiment only — never commit it.
+- **`scripts/lib/telemetry/lib` is a symlink** to the repo-root `shared/telemetry/lib` — edit `shared/telemetry/lib/` directly; there is no copy to re-sync. The real files under `scripts/lib/telemetry/` are `ikey.json` (this plugin's config) and `resolver.js` (the resolver contract implementation). **Posture:** the committed `ikey.json` ships `disabled: false` — transmission is enabled for power-pages (the tenant-side Kusto stream + annotation for `PagesAIPluginEvent` are provisioned). Set `disabled: true` to hard-off (no POST, no local log) if you need to suppress all telemetry at the source.
 - **Region routing (Artemis geo + cloud stamp)** lives in `scripts/lib/telemetry/region/` and is wired through `scripts/lib/telemetry/resolver.js`, which implements the resolver contract (`resolve({ event, cfg, cloud, configDir })` / `isProvisioned(cfg)`). The shared dispatcher is routing-agnostic — it auto-discovers `resolver.js` by convention (sibling of `ikey.json`) and calls it; the `region/` implementation is entirely plugin-owned and never referenced by the shared library.
-- **Privacy posture:** anonymous telemetry is **default-on**. There is no consent prompt in skills. Users opt out via `/power-pages:telemetry off`, which stores a per-plugin choice in `~/.power-platform-skills/config.json` (`telemetry["power-pages"] = "off"`). Opting out stops transmission only; the local diagnostic mirror is still written. Re-enable with `/power-pages:telemetry on`.
+- **Privacy posture:** anonymous telemetry is **default-on**. There is no consent prompt in skills. Users opt out via `/power-pages:telemetry off`, which stores a per-plugin choice in `~/.power-platform-skills/config.json` (`telemetry["power-pages"] = "off"`). Opting out stops transmission only; the local diagnostic mirror is still written. Re-enable with `/power-pages:telemetry on`. Automation/CI can disable transmission by setting `POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1` (or `true`); this opt-out has the **highest precedence** — it overrides both a persisted `/power-pages:telemetry` choice and `/power-pages:telemetry on`. Transmission-only suppression — the local mirror is still written.
 - **Strict allowlist:** `shared/telemetry/lib/events.js` enforces exactly the fields listed in the spec. Never add a field to a builder without first adding it to the allowlist and documenting it in the design doc.
 - **Fail closed:** telemetry code must never change a script's exit code or break a skill run. Emission is fire-and-forget via a detached dispatcher child, so the hook or script returns before the HTTPS POST completes.
 

plugins/power-pages/README.md

@@ -399,6 +399,7 @@ Enables, disables, or checks the status of anonymous usage telemetry. Per-user a
 - `/power-pages:telemetry off` — stop sending telemetry (nothing leaves your machine)
 - `/power-pages:telemetry on` — resume sending telemetry
 - No personal data is ever collected (anonymous: skill name, plugin version, OS, Node version)
+- Automation/CI: set `POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1` to disable (highest precedence — overrides any saved choice)
 
 ## Agents
 
@@ -524,8 +525,20 @@ inputs, site names, URLs, credentials, usernames, or hostnames.
 When **off**, nothing leaves your machine. A local diagnostic copy of each event
 is still written to `~/.power-platform-skills/events.jsonl` so you can see exactly
 what would have been sent; delete it anytime. The setting is stored at
-`~/.power-platform-skills/config.json` (`{ "telemetry": { "power-pages": "off" } }`),
-so CI/headless environments can opt out by writing that file directly.
+`~/.power-platform-skills/config.json`
+(`{ "telemetry": { "power-pages": "off" } }`).
+
+For automation / CI, set the per-plugin opt-out environment variable instead of
+editing that file:
+
+```bash
+POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1   # stop sending telemetry
+```
+
+Set it to `1` or `true` (dotnet `*_TELEMETRY_OPTOUT` convention). This opt-out has
+the **highest precedence** — it overrides a saved `/power-pages:telemetry` choice
+and even `/power-pages:telemetry on`. Like `off` from the command, it suppresses
+transmission only — the local `events.jsonl` mirror is still written.
 
 ## License
 

plugins/power-pages/scripts/lib/telemetry/ikey.json

@@ -1,6 +1,6 @@
 {
   "event_stream_name": "PagesAIPluginEvent",
-  "disabled": true,
+  "disabled": false,
   "default_region": "us",
   "regions": {
     "internal": {

shared/skills/telemetry/telemetry-workflow.md

@@ -17,11 +17,17 @@ usage telemetry for this plugin. Default to `status` when no argument is given.
 
 ## What to know (for answering follow-ups)
 
-- `off` stops transmission to Microsoft. **Nothing leaves the machine.** A local
-  diagnostic log is still written at `~/.power-platform-skills/events.jsonl`.
+- `off` stops transmission to Microsoft. **Nothing leaves the machine.**.
 - `on` re-enables transmission. The choice is **per-user and per-plugin** and
   takes effect on the next event (no restart).
 - **No personal data is ever collected.** Telemetry is anonymous: it records only
   things like skill name, plugin version, OS, and Node version. It never includes
   file paths, prompts, tool inputs, site names, URLs, credentials, usernames, or
   hostnames.
+- **Automation/CI** can disable telemetry by setting the opt-out env var
+  `POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT` (e.g.
+  `POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1`) instead of running this
+  command. Set it to `1` or `true` (the dotnet `*_TELEMETRY_OPTOUT` convention).
+  `<PLUGIN>` is the plugin name uppercased with non-alphanumerics collapsed to `_`.
+  This opt-out has the highest precedence — it overrides a saved choice from this
+  command and even `on`. It suppresses transmission only, like `off`.

shared/telemetry/README.md

@@ -22,7 +22,7 @@ hook (~5ms when disabled, ~3-5s otherwise — incl. when the user opted out)
             ├─ kill switch (cfg.disabled) → exit   ← HARD OFF: no local log, no POST
             ├─ sanitizeData (FIELD_TYPES allowlist)
             ├─ appendLocal({time,name,data}) → events.jsonl   ← ALWAYS (the mirror)
-            ├─ user opt-out (config.json telemetry[plugin]="off") → exit (mirror written, no POST)
+            ├─ user opt-out (env var POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT=1 OR config.json choice "off"; env wins) → exit (mirror written, no POST)
             ├─ resolve destination → iKey + collector_url   ← resolver.js (plugin) or static key
             ├─ iKey missing/placeholder → exit (mirror already written, no POST)
             ├─ build CS4.0 envelope (same time + sanitized data)
@@ -98,6 +98,14 @@ The dispatcher runs a defense-in-depth allowlist filter against `FIELD_TYPES` be
 
 - **Default-on.** Anonymous telemetry is enabled by default. No first-run prompt.
 - **Opt out of transmission** via `/<plugin>:telemetry off` (per-user, per-plugin). This writes `telemetry[<plugin>] = "off"` into `~/.power-platform-skills/config.json` and stops the network POST to the collector — **nothing leaves the machine** — but the local diagnostic mirror (`events.jsonl`) is still written so the user/developer can see exactly what would have been sent. It is therefore an opt-out of *transmission*, not of local logging. CI/headless can opt out by writing that file directly. Re-enable with `/<plugin>:telemetry on`.
+- **Opt out for automation** via the per-plugin opt-out env var
+  `POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT` (e.g.
+  `POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT=1`). Set it to `1` or `true`
+  (the dotnet `*_TELEMETRY_OPTOUT` convention) to disable transmission; it only
+  disables, never re-enables. It has the **highest precedence** — it overrides a
+  persisted `config.json` choice and `/<plugin>:telemetry on`. The dispatcher reads
+  it inside the transmission gate, after the local mirror is written, so it
+  suppresses transmission only — the local mirror is still written.
 - **Repo-side kill switch (true hard-off).** `ikey.json` carries a `disabled` flag. When `true` (or when `ikey.json` is missing/unreadable), every entry point — hooks, `emit-from-prompt`, and the dispatcher — short-circuits BEFORE any PAC shellout or process spawn, so there is **no POST and no local log**. Ship `true` and flip to `false` only after the tenant-side Kusto stream and annotation are provisioned.
 
 The `disabled` flag is checked at every layer that could perform user-facing work: the pretool/posttool hooks and `emit-from-prompt.js`. A disabled plugin emits zero side effects. The per-plugin user opt-out, by contrast, is enforced inside the detached dispatcher AFTER the local mirror is written — so an opted-out run still produces `events.jsonl` (and incurs the same event-building cost as an enabled run) but never transmits.

shared/telemetry/lib/telemetry-config.js

@@ -4,7 +4,7 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
-const { readTelemetryChoice, setTelemetryChoice } = require("./user-config");
+const { setTelemetryChoice, effectiveTelemetryChoice } = require("./user-config");
 
 const ANONYMITY =
   "ℹ️  No personal data is collected. Telemetry is anonymous — it records only\n" +
@@ -58,7 +58,7 @@ function main() {
   const dir = configDir();
 
   if (action === "status") {
-    const on = readTelemetryChoice(dir, plugin) !== "off"; // default ON
+    const on = effectiveTelemetryChoice(dir, plugin) !== "off"; // default ON; honors env override when no stored choice
     if (on) {
       out(`Telemetry (${plugin}): ON`);
       out(ANONYMITY);

shared/telemetry/lib/user-config.js

@@ -31,8 +31,40 @@ function readTelemetryChoice(configDir, pluginName) {
   return v === "on" || v === "off" ? v : null;
 }
 
-function isTransmissionOptedOut(configDir, pluginName) {
-  return readTelemetryChoice(configDir, pluginName) === "off";
+// Builds the per-plugin opt-out var name: POWER_PLATFORM_SKILLS_TELEMETRY_<PLUGIN>_OPTOUT
+// where <PLUGIN> is the plugin name uppercased with non-alphanumeric runs -> "_".
+function telemetryOptOutEnvVarName(pluginName) {
+  return (
+    "POWER_PLATFORM_SKILLS_TELEMETRY_" +
+    String(pluginName).toUpperCase().replace(/[^A-Z0-9]+/g, "_") +
+    "_OPTOUT"
+  );
+}
+
+// True when the per-plugin opt-out env var is set to a truthy value (`1` or
+// `true`, case-insensitive). Follows the dotnet `*_TELEMETRY_OPTOUT` convention:
+// the var only disables — it is never used to re-enable. Unset / empty / `0` /
+// `false` / anything else => not opted out. `env` is injectable so tests never
+// mutate the real process.env.
+function readTelemetryEnvOptOut(pluginName, env = process.env) {
+  if (!pluginName) return false;
+  const v = String(env[telemetryOptOutEnvVarName(pluginName)] || "").trim().toLowerCase();
+  return v === "1" || v === "true";
+}
+
+// Resolves the effective on/off choice by precedence (highest first):
+//   1. the env-var opt-out (when truthy => "off"; overrides everything below)
+//   2. persisted config.json per-plugin choice (set via the slash skill)
+//   3. null = default-on
+// The env var has the highest precedence and can only force "off"; it never
+// re-enables a config opt-out.
+function effectiveTelemetryChoice(configDir, pluginName, env = process.env) {
+  if (readTelemetryEnvOptOut(pluginName, env)) return "off";
+  return readTelemetryChoice(configDir, pluginName) ?? null;
+}
+
+function isTransmissionOptedOut(configDir, pluginName, env = process.env) {
+  return effectiveTelemetryChoice(configDir, pluginName, env) === "off";
 }
 
 // Merge-writes { telemetry: { [pluginName]: choice } }, preserving every other
@@ -60,5 +92,8 @@ module.exports = {
   readTelemetryChoice,
   setTelemetryChoice,
   isTransmissionOptedOut,
+  telemetryOptOutEnvVarName,
+  readTelemetryEnvOptOut,
+  effectiveTelemetryChoice,
   CONFIG_FILE_NAME,
 };

shared/telemetry/tests/emit-dispatcher.test.js

@@ -50,6 +50,7 @@ function runDispatcher({ event, env }) {
       POWER_PLATFORM_SKILLS_FAKE_HTTPS: env.fakeProbe || "",
       POWER_PLATFORM_SKILLS_IKEY_JSON: ikeyJsonPath,
       POWER_PLATFORM_SKILLS_CLOUD: env.cloud || "",
+      POWER_PLATFORM_SKILLS_TELEMETRY_POWER_PAGES_OPTOUT: env.optOut || "",
     },
   });
 }
@@ -501,3 +502,52 @@ test("dispatcher writes the mirror but does NOT POST when neither resolver nor s
   assert.ok(!fs.existsSync(probePath), "no key resolved → no POST");
   assert.ok(fs.existsSync(path.join(tmp, "events.jsonl")), "local mirror still written");
 });
+
+test("env opt-out (no config choice) suppresses the POST but still writes the mirror", () => {
+  const tmp = mkTmp();
+  const probePath = path.join(tmp, "probe.json");
+  const { status } = runDispatcher({
+    event: fakeEvent,
+    env: {
+      configDir: tmp,
+      iKey: "real-ikey-32-chars-minimum-aaaaaaaaaaaaaa",
+      collectorUrl: "https://example.invalid/OneCollector/1.0/",
+      fakeProbe: probePath,
+      optOut: "1",
+    },
+  });
+  assert.equal(status, 0);
+  assert.ok(!fs.existsSync(probePath), "env opt-out must skip the POST");
+  assert.ok(
+    fs.existsSync(path.join(tmp, "events.jsonl")),
+    "env opt-out must still write the local mirror"
+  );
+});
+
+test("env opt-out overrides a persisted 'on' choice (env wins) — no POST", () => {
+  const tmp = mkTmp();
+  const probePath = path.join(tmp, "probe.json");
+  fs.writeFileSync(
+    path.join(tmp, "config.json"),
+    JSON.stringify({ telemetry: { "power-pages": "on" } })
+  );
+  const { status } = runDispatcher({
+    event: fakeEvent,
+    env: {
+      configDir: tmp,
+      iKey: "real-ikey-32-chars-minimum-aaaaaaaaaaaaaa",
+      collectorUrl: "https://example.invalid/OneCollector/1.0/",
+      fakeProbe: probePath,
+      optOut: "1",
+    },
+  });
+  assert.equal(status, 0);
+  assert.ok(
+    !fs.existsSync(probePath),
+    "env opt-out has highest precedence → must skip the POST even with config 'on'"
+  );
+  assert.ok(
+    fs.existsSync(path.join(tmp, "events.jsonl")),
+    "opt-out suppresses transmission only — the local mirror is still written"
+  );
+});