@michaelschnyder/teams-cli 0.2.0-canary.7.1.g64541e1a → 0.2.0

package/README.md

@@ -109,7 +109,7 @@ Person, chat, channel, and message commands support `--json`. JSON payloads stay
 | Command | Purpose | Examples and details |
 | --- | --- | --- |
 | `login` | Sign in using the default session; alias for `auth login` | [Authentication](docs/use/authentication.md) |
-| `version` | Inspect build provenance, check for updates, or select the notification channel | [Installation and upgrades](docs/use/installation.md) |
+| `version` | Inspect build provenance, install updates, or switch stable/canary channels | [Installation and upgrades](docs/use/installation.md) |
 | `skills` | List, locate, install, and refresh the packaged agent skill | [Agent skill installation](docs/use/agent-skills.md) |
 | `doctor` | Diagnose the local runtime, browser, session, and managed skills without changing them | [Installation and upgrades](docs/use/installation.md#troubleshooting) |
 | `auth` | Login, refresh, inspect, export tokens, or logout | [Authentication](docs/use/authentication.md) |

package/dist/build-info.json

@@ -1,34 +1,32 @@
 {
   "schemaVersion": 1,
-  "version": "0.2.0-canary.7.1.g64541e1a",
-  "channel": "canary",
-  "builtAt": "2026-09-04T10:54:53.370Z",
+  "version": "0.2.0",
+  "channel": "stable",
+  "builtAt": "2026-09-04T11:47:26.658Z",
   "source": {
-    "branch": "codex/fix-canary-provenance-race",
-    "commit": "64541e1a22a00f539a23ee66d67aa70d33f47f8c",
-    "commitUrl": "https://github.com/michaelschnyder/teams-cli/commit/64541e1a22a00f539a23ee66d67aa70d33f47f8c",
-    "pullRequest": 14,
-    "pullRequestUrl": "https://github.com/michaelschnyder/teams-cli/pull/14",
-    "author": "michaelschnyder"
+    "branch": "main",
+    "commit": "0f109289ab1398dbf4c8717bb91df07588a96bc0",
+    "commitUrl": "https://github.com/michaelschnyder/teams-cli/commit/0f109289ab1398dbf4c8717bb91df07588a96bc0",
+    "author": "Michael Schnyder <michael.schnyder@outlook.com>"
   },
   "trigger": {
-    "kind": "merged-pull-request",
+    "kind": "release",
     "actor": "michaelschnyder"
   },
   "runner": {
-    "name": "GitHub Actions 1000001086",
+    "name": "GitHub Actions 1000001109",
     "os": "Linux",
     "architecture": "X64"
   },
   "workflow": {
-    "runId": "33865033307",
-    "runNumber": "7",
+    "runId": "33869547336",
+    "runNumber": "11",
     "runAttempt": "1",
-    "url": "https://github.com/michaelschnyder/teams-cli/actions/runs/33865033307"
+    "url": "https://github.com/michaelschnyder/teams-cli/actions/runs/33869547336"
   },
   "releaseNotes": {
-    "title": "Fix canary provenance race after rapid merges",
-    "body": "## Summary\n\n- derive publication provenance from the commit actually checked out for the completed CI run\n- reject a canary when the checkout and workflow-run commit differ\n- defer commit-author lookup until the authoritative source commit is selected\n- cover the rapid-merge mismatch with a regression test\n\n## Verification\n\n- `node --check scripts/prepare-publication.mjs`\n- `node --import tsx --test test/release-metadata.test.ts`\n- `npm run check`\n- `CI=true npm test` (105 tests)\n- `npm run build`\n- `npm run package:check`\n- `npm run package:smoke`\n- GitHub CI on Ubuntu, macOS, and Windows; the Ubuntu dependency audit passed",
-    "url": "https://github.com/michaelschnyder/teams-cli/pull/14"
+    "title": "Teams CLI v0.2.0",
+    "body": "## Highlights\n\n### Create workspace safeguards visually\n\n`teams-cli policy edit --open` now launches a local policy editor where you can choose which people, group chats, and channels may be read or posted to. You can review the generated policy, save a draft, and activate it when ready.\n\nRead and post access are configured independently, explicit denials take priority, and overlapping active policies can only narrow access. The editor keeps Teams credentials and message content out of the browser UI.\n\n### Get started with fewer identifiers and commands\n\n- `teams-cli login` signs in and discovers the default tenant and user automatically. Most users no longer need to provide tenant IDs, user IDs, or named profiles.\n- `teams-cli message send --person alice@example.com --body \"Hello\"` can find or start a direct conversation without requiring you to discover a chat ID first.\n- `teams-cli chat search \"Alice\" --json` uses bounded, server-ranked search instead of downloading your complete chat collection.\n\n### Set up coding agents more easily\n\nThe packaged guidance is now one consolidated `teams-cli` skill covering authentication, discovery, reading, messaging, and policies. `teams-cli skills install` installs or refreshes it for supported filesystem-based agents and migrates managed skills from version 0.1 automatically.\n\nClaude Desktop users also receive a versioned Cowork skill ZIP that can be uploaded through Cowork's skill settings. Interactive first-time login can offer agent-skill setup before authentication.\n\n### Diagnose local setup problems\n\nThe new `teams-cli doctor` command checks Node.js and browser availability, the selected identity, session health, managed skills, and detected agent environments without changing your configuration or contacting Teams. Use `teams-cli doctor --json` for structured output.\n\n### Try upcoming builds and stay updated\n\nThe CLI now supports stable and canary update channels, plus immutable branch snapshots for targeted testing. `teams-cli version` shows the installed channel, build provenance, release notes, and available updates. Globally installed stable and canary versions can update themselves with `teams-cli version --upgrade`; snapshot builds remain pinned until you explicitly switch channels.\n\n## Upgrade\n\nFor a global npm installation, run:\n\n```console\nteams-cli version --upgrade\n```\n\nYou can also install the release directly:\n\n```console\nnpm install --global @michaelschnyder/teams-cli@latest\n```\n\nIf you created a policy with version 0.1, open `teams-cli policy edit --open` and recreate it using the new people, group-chat, and channel read/post permissions. The previous `messageSend` policy shape is no longer accepted.\n\n> [!WARNING]\n> This project uses unsupported Microsoft Teams private APIs. Microsoft may change or block them without notice. Obtain organizational approval before use.\n",
+    "url": "https://github.com/michaelschnyder/teams-cli/releases/tag/v0.2.0"
   }
 }

package/dist/cli.js

@@ -466,6 +466,7 @@ export function createProgram(options = {}) {
         .showHelpAfterError();
     const versionOptions = {
         ...(options.storageRoot ? { storageRoot: options.storageRoot } : {}),
+        confirm: interactiveAuth.confirm,
         ...(options.fetcher ? { fetcher: options.fetcher } : {}),
         ...(options.environment ? { environment: options.environment } : {}),
     };

package/dist/commands/version.js

@@ -2,7 +2,8 @@ import { Option } from "commander";
 import { stripVTControlCharacters } from "node:util";
 import { storagePaths } from "../storage.js";
 import { resolveUpdateChannel, saveUpdateChannel } from "../settings.js";
-import { checkForUpdate, isNpxExecution, updateChecksDisabled } from "../update.js";
+import { checkForUpdate, isNpxExecution, latestForChannel, updateChecksDisabled } from "../update.js";
+import { canUpgradeCli, upgradeCli } from "../upgrade.js";
 import { BUILD_INFO, CLI_VERSION, PACKAGE_NAME } from "../version.js";
 function safe(value) {
     return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
@@ -47,7 +48,7 @@ export function renderVersion(info, channel, candidate, updateStatus = candidate
             lines.push(safe(candidate.summary.summary));
         if (candidate.summary?.url)
             lines.push(safe(candidate.summary.url));
-        lines.push(`Update with the package manager and installation scope that installed the CLI, targeting ${PACKAGE_NAME}@${candidate.version}.`);
+        lines.push(`For a global npm installation, run \`teams-cli version --upgrade\`. Otherwise update through the package manager and installation scope that installed the CLI, targeting ${PACKAGE_NAME}@${candidate.version}.`);
     }
     else if (updateStatus === "current") {
         lines.push("", "No update is currently available.");
@@ -58,12 +59,13 @@ async function versionDetails(options) {
     const environment = options.environment ?? process.env;
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
+    const buildInfo = options.buildInfo ?? BUILD_INFO;
     const paths = storagePaths(options.storageRoot);
-    const channel = await resolveUpdateChannel({ paths, environment, installedChannel: BUILD_INFO.channel });
+    const channel = await resolveUpdateChannel({ paths, environment, installedChannel: buildInfo.channel });
     const npx = isNpxExecution(environment);
     let candidate = null;
     let updateStatus = "current";
-    if (BUILD_INFO.channel === "snapshot")
+    if (buildInfo.channel === "snapshot")
         updateStatus = "pinned";
     else if (npx)
         updateStatus = "npx";
@@ -71,7 +73,7 @@ async function versionDetails(options) {
         updateStatus = "disabled";
     else {
         try {
-            candidate = await checkForUpdate(CLI_VERSION, channel, options.fetcher);
+            candidate = await checkForUpdate(buildInfo.version, channel, options.fetcher);
             updateStatus = candidate ? "available" : "current";
         }
         catch {
@@ -79,48 +81,76 @@ async function versionDetails(options) {
         }
     }
     if (options.json) {
-        stdout.write(`${JSON.stringify({ installed: BUILD_INFO, updateChannel: channel, update: { status: updateStatus, candidate } }, null, 2)}\n`);
+        stdout.write(`${JSON.stringify({ installed: buildInfo, updateChannel: channel, update: { status: updateStatus, candidate } }, null, 2)}\n`);
         return;
     }
-    stdout.write(renderVersion(BUILD_INFO, channel, candidate, updateStatus));
+    stdout.write(renderVersion(buildInfo, channel, candidate, updateStatus));
     if (updateStatus === "pinned")
         stderr.write("Snapshot builds are pinned. Replace this build explicitly through your package manager to leave the snapshot.\n");
     if (updateStatus === "npx")
         stderr.write("This temporary npx execution manages its version through the package spec, not the CLI updater.\n");
     if (updateStatus === "unavailable")
         stderr.write("The npm registry could not be checked; installed build information is still complete.\n");
+    if (candidate && options.allowPrompt && options.confirm && await (options.canUpgrade ?? canUpgradeCli)() &&
+        await options.confirm(`Install teams-cli ${candidate.version}?`)) {
+        stderr.write(`Upgrading teams-cli to ${candidate.version} through npm…\n`);
+        await (options.upgrader ?? upgradeCli)({ targetVersion: candidate.version });
+        stdout.write("teams-cli and recorded skill installations are up to date.\n");
+    }
 }
 async function changeChannel(channel, options) {
     const environment = options.environment ?? process.env;
     if (isNpxExecution(environment)) {
-        throw new Error(`Cannot change persistent settings from npx. Run \`npx --prefer-online ${PACKAGE_NAME}@${channel === "stable" ? "latest" : "canary"} --version\` instead.`);
+        throw new Error(`Cannot switch an installation channel from npx. Run \`npx --prefer-online ${PACKAGE_NAME}@${channel === "stable" ? "latest" : "canary"} --version\` instead.`);
     }
     const paths = storagePaths(options.storageRoot);
-    await saveUpdateChannel(paths, channel);
-    const tag = channel === "stable" ? "latest" : "canary";
-    (options.stdout ?? process.stdout).write(`teams-cli now checks the ${channel} channel. Update with the package manager and installation scope that installed the CLI, targeting ${PACKAGE_NAME}@${tag}.\n`);
-    if (BUILD_INFO.channel === "snapshot") {
-        (options.stderr ?? process.stderr).write("This installed snapshot remains pinned until you replace it through your package manager.\n");
+    const candidate = await latestForChannel(channel, options.fetcher);
+    (options.stderr ?? process.stderr).write(`Switching teams-cli to ${channel} (${candidate.version})…\n`);
+    await (options.upgrader ?? upgradeCli)({
+        targetVersion: candidate.version,
+        onInstalled: () => saveUpdateChannel(paths, channel),
+    });
+    (options.stdout ?? process.stdout).write(`teams-cli now follows the ${channel} channel at ${candidate.version}.\n`);
+}
+async function upgradeCurrent(options) {
+    const environment = options.environment ?? process.env;
+    if (isNpxExecution(environment)) {
+        throw new Error(`Cannot upgrade a temporary npx execution. Run \`npx --prefer-online ${PACKAGE_NAME}@latest --version\` instead.`);
+    }
+    const buildInfo = options.buildInfo ?? BUILD_INFO;
+    if (buildInfo.channel === "snapshot") {
+        throw new Error("Snapshot builds are pinned. Use `teams-cli version --channel stable` or `--channel canary` to leave this snapshot.");
     }
+    const paths = storagePaths(options.storageRoot);
+    const channel = await resolveUpdateChannel({ paths, environment, installedChannel: buildInfo.channel });
+    const candidate = await latestForChannel(channel, options.fetcher);
+    (options.stderr ?? process.stderr).write(`Upgrading teams-cli on ${channel} to ${candidate.version}…\n`);
+    await (options.upgrader ?? upgradeCli)({ targetVersion: candidate.version });
+    (options.stdout ?? process.stdout).write("teams-cli and recorded skill installations are up to date.\n");
 }
 export function registerVersionCommand(program, options = {}) {
     program.command("version")
-        .description("Show build provenance or manage the update-notification channel")
-        .addOption(new Option("--channel <channel>", "Select the update-notification channel").choices(["stable", "canary"]))
+        .description("Show build provenance, manage the update channel, or upgrade a global npm installation")
+        .option("--upgrade", "Install the newest version from the effective channel")
+        .addOption(new Option("--channel <channel>", "Switch a global npm installation channel").choices(["stable", "canary"]))
         .option("--json", "Output structured build and update information")
         .action(async (commandOptions) => {
-        if (commandOptions.json && commandOptions.channel)
-            throw new Error("--json cannot be combined with --channel");
+        if (commandOptions.channel && commandOptions.upgrade)
+            throw new Error("--channel already installs the newest version and cannot be combined with --upgrade");
+        if (commandOptions.json && (commandOptions.channel || commandOptions.upgrade))
+            throw new Error("--json cannot be combined with --channel or --upgrade");
         if (commandOptions.channel)
             return changeChannel(commandOptions.channel, options);
-        return versionDetails({ ...options, json: commandOptions.json === true });
+        if (commandOptions.upgrade)
+            return upgradeCurrent(options);
+        return versionDetails({ ...options, json: commandOptions.json === true, allowPrompt: true });
     });
 }
 export async function showAdaptiveVersion(options = {}) {
     const stdout = options.stdout ?? process.stdout;
     if (!stdout.isTTY) {
-        stdout.write(`${CLI_VERSION}\n`);
+        stdout.write(`${options.buildInfo?.version ?? CLI_VERSION}\n`);
         return;
     }
-    await versionDetails(options);
+    await versionDetails({ ...options, allowPrompt: true });
 }

package/dist/skills/teams-cli/SKILL.md

@@ -3,7 +3,7 @@ name: teams-cli
 description: Use teams-cli safely for Microsoft Teams authentication, discovery, reading, messaging, and policies.
 license: MIT
 metadata:
-  version: "0.2.0-canary.7.1.g64541e1a"
+  version: "0.2.0"
   author: teams-cli
 ---
 

package/dist/update.js

@@ -135,7 +135,7 @@ export async function prepareUpdateNotification(options) {
     if (state && state.channel === channel && state.pendingVersion && isNewerVersion(options.currentVersion, state.pendingVersion)) {
         const description = state.pendingSummary?.title ? ` ${state.pendingSummary.title}.` : "";
         (options.stderr ?? process.stderr).write(`A new teams-cli ${channel} version is available: ${options.currentVersion} → ${state.pendingVersion}.${description} ` +
-            `Update through the package manager and installation scope that installed it, targeting ${PACKAGE_NAME}@${state.pendingVersion}.\n`);
+            `For a global npm installation, run \`teams-cli version --upgrade\`. Otherwise update through the package manager and installation scope that installed it, targeting ${PACKAGE_NAME}@${state.pendingVersion}.\n`);
         const consumed = { ...state };
         delete consumed.pendingVersion;
         delete consumed.pendingSummary;

package/dist/upgrade.js

@@ -0,0 +1,97 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { PACKAGE_NAME } from "./version.js";
+const execFileAsync = promisify(execFile);
+const PACKAGE_ROOT = dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+export function npmInvocation(platform = process.platform, nodeExecutable = process.execPath, npmExecPath = process.env.npm_execpath) {
+    if (npmExecPath)
+        return { command: nodeExecutable, args: [npmExecPath] };
+    if (platform === "win32") {
+        return {
+            command: nodeExecutable,
+            args: [win32.join(win32.dirname(nodeExecutable), "node_modules", "npm", "bin", "npm-cli.js")],
+        };
+    }
+    return { command: "npm", args: [] };
+}
+async function defaultGlobalRoot(npm) {
+    const { stdout } = await execFileAsync(npm.command, [...npm.args, "root", "--global"], {
+        encoding: "utf8",
+        windowsHide: true,
+    });
+    const root = stdout.trim();
+    if (!root)
+        throw new Error("npm returned no global package root");
+    return root;
+}
+function comparablePath(path, platform) {
+    const absolute = resolve(path);
+    return platform === "win32" ? absolute.toLowerCase() : absolute;
+}
+export async function resolveGlobalNpmInstallation(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const npm = options.npm ?? npmInvocation(platform);
+    let globalRoot;
+    try {
+        globalRoot = await (options.globalRoot ?? defaultGlobalRoot)(npm);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? `: ${error.message}` : "";
+        throw new Error(`Cannot verify the npm global installation scope${detail}`);
+    }
+    const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
+    const expectedRoot = join(globalRoot, ...PACKAGE_NAME.split("/"));
+    const canonicalize = options.canonicalize ?? realpathSync;
+    let actual;
+    let expected;
+    try {
+        actual = canonicalize(packageRoot);
+        expected = canonicalize(expectedRoot);
+    }
+    catch {
+        throw new Error("Cannot verify that this teams-cli package belongs to npm's global installation scope");
+    }
+    if (comparablePath(actual, platform) !== comparablePath(expected, platform)) {
+        throw new Error("Automatic upgrade is available only for a global npm installation managed by the active npm executable. " +
+            "Update this package through the package manager and installation scope that installed it.");
+    }
+    return {
+        npm,
+        globalRoot,
+        packageRoot: actual,
+        installedCli: join(expectedRoot, "dist", "cli.js"),
+    };
+}
+export async function canUpgradeCli(options = {}) {
+    try {
+        await resolveGlobalNpmInstallation(options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const defaultRunner = (command, args) => new Promise((resolveRun, reject) => {
+    const child = spawn(command, [...args], { stdio: "inherit", shell: false, windowsHide: true });
+    child.once("error", reject);
+    child.once("exit", (code) => resolveRun(code ?? 1));
+});
+export async function upgradeCli(options = {}) {
+    const installation = await resolveGlobalNpmInstallation(options);
+    const runner = options.runner ?? defaultRunner;
+    const targetVersion = options.targetVersion ?? "latest";
+    const installStatus = await runner(installation.npm.command, [...installation.npm.args, "install", "--global", `${PACKAGE_NAME}@${targetVersion}`]);
+    if (installStatus !== 0)
+        throw new Error(`npm upgrade failed with exit code ${installStatus}`);
+    if (!(options.pathExists ?? existsSync)(installation.installedCli)) {
+        throw new Error(`The updated CLI was not found at ${installation.installedCli}`);
+    }
+    await options.onInstalled?.();
+    const reinstallStatus = await runner(process.execPath, [installation.installedCli, "skills", "reinstall"]);
+    if (reinstallStatus !== 0) {
+        throw new Error(`The CLI was upgraded, but skill reinstallation failed with exit code ${reinstallStatus}`);
+    }
+}

package/docs/releasing.md

@@ -37,7 +37,7 @@ Published npm versions are immutable. If a release is defective, fix it in a new
 
 ## Canary releases
 
-Merging a pull request into `main` publishes one prerelease to the `canary` npm tag after the resulting main-branch CI run passes on Ubuntu, macOS, and Windows. The publishing workflow consumes that successful CI result instead of repeating the operating-system matrix. A direct commit to `main` does not publish. Stable releases and manually requested snapshots run package verification on Ubuntu before publishing. The workflow uses the package version when it is already greater than npm's latest stable release; otherwise it assumes the next patch. Versions include the workflow run, attempt, and source commit, while the package embeds the pull request notes and build provenance.
+Merging a pull request into `main` publishes one prerelease to the `canary` npm tag after the resulting main-branch CI run passes on Ubuntu, macOS, and Windows. The publishing workflow consumes that successful CI result instead of repeating the operating-system matrix. A direct commit to `main` does not publish. Stable releases run package verification on Ubuntu without repeating the dependency audit that already gates `main`; manually requested snapshots include the audit because their selected branch might not have passed `main` CI. The workflow uses the package version when it is already greater than npm's latest stable release; otherwise it assumes the next patch. Versions include the workflow run, attempt, and source commit, while the package embeds the pull request notes and build provenance.
 
 Install or follow this channel with:
 
@@ -46,8 +46,10 @@ npm install --global @michaelschnyder/teams-cli@canary
 teams-cli version --channel canary
 ```
 
+The npm command is useful when installing canary for the first time or upgrading from a release that predates channel switching. Once the channel-aware CLI is installed globally through npm, `version --channel canary` installs the newest canary and records the selection.
+
 ## Branch snapshots
 
 Repository contributors with write, maintain, or admin permission can run the publish workflow from `main` and enter a repository branch to snapshot. Manual runs are automatically classified as snapshot publications. The workflow verifies that the requested branch and checked-out commit belong to this repository; fork refs and dispatches using a modified branch workflow are not accepted. It publishes an immutable `snapshot` prerelease, associates an npm tag with the selected branch, and prints exact global-install and npx commands in its summary. Canary summaries provide both commands as well.
 
-Snapshots never update automatically. Testers leave a snapshot by explicitly installing `latest` or `canary` through their package manager and selecting the corresponding notification channel.
+Snapshots never update automatically and `version --upgrade` refuses to replace them. Testers with a global npm installation can leave a snapshot explicitly with `version --channel stable` or `version --channel canary`; other installation scopes must use their owning package manager.

package/docs/use/commands.md

@@ -8,9 +8,11 @@ The default session created by `teams-cli login` or `teams-cli auth login` is us
 teams-cli --version
 teams-cli version
 teams-cli version --json
+teams-cli version --upgrade
+teams-cli version --channel canary
 ```
 
-When piped, `--version` prints only semantic version text. In a terminal, version output includes the installed channel, local build provenance, associated release notes, and any available update. The policy editor shows the same exact version in its footer.
+When piped, `--version` prints only semantic version text. In a terminal, version output includes the installed channel, local build provenance, associated release notes, and any available update. A verified global npm installation can accept the interactive update offer or use `version --upgrade`; npx, snapshots, project dependencies, and installations owned by another package manager are not changed automatically. Use an explicit `--channel stable|canary` to replace a global npm installation and persist that channel after installation succeeds. The policy editor shows the same exact version in its footer.
 
 ## Diagnose the local setup
 

package/docs/use/installation.md

@@ -80,20 +80,18 @@ At startup, the CLI may launch a detached npm registry check. It runs at most on
 Stable installations follow npm's `latest` tag. Switch to builds produced from newly merged pull requests with:
 
 ```bash
-npm install --global @michaelschnyder/teams-cli@canary
 teams-cli version --channel canary
 ```
 
-The npm command replaces the globally installed package, while the CLI command records which channel should be checked for update notifications in `~/.teams-cli/settings.yaml`. Switch back in the same way:
+For a global npm installation, this installs the newest canary and records the channel in `~/.teams-cli/settings.yaml` only after installation succeeds. Switch back in the same way:
 
 ```bash
-npm install --global @michaelschnyder/teams-cli@latest
 teams-cli version --channel stable
 ```
 
 `TEAMS_CLI_UPDATE_CHANNEL=stable|canary` overrides the recorded channel for the current process. Channel settings are user-wide and deliberately separate from Teams profiles and workspace policies.
 
-Contributor snapshots are installed using the exact version shown by their GitHub Actions run. Snapshots are pinned and do not perform background update checks. Replace a snapshot explicitly through the same package manager and installation scope that installed it, then select `stable` or `canary` for future notifications.
+Contributor snapshots are installed using the exact version shown by their GitHub Actions run. Snapshots are pinned: they do not perform background update checks and `version --upgrade` refuses to replace them. A globally installed snapshot can leave the pinned build through an explicit `teams-cli version --channel stable` or `--channel canary` command.
 
 Disable checks with either environment variable:
 
@@ -103,11 +101,15 @@ export NO_UPDATE_NOTIFIER=1
 export TEAMS_CLI_DISABLE_UPDATE_CHECK=1
 ```
 
-Checks are automatically disabled in CI and temporary npx executions. Inspect local build provenance and any associated release notes with `teams-cli version`, or use `teams-cli version --json` for structured output.
+Checks are automatically disabled in CI and temporary npx executions. Inspect local build provenance and any associated release notes with `teams-cli version`, or use `teams-cli version --json` for structured output. An interactive version check offers to install an available update when the running package is verified as a global npm installation. Upgrade explicitly within the effective stable or canary channel with:
 
-The CLI does not run npm or change global or project dependencies itself, because it cannot reliably determine the package manager and installation scope that installed it. Update notices provide an exact package target. Use `npm install --global` only for an existing global npm installation; for a project dependency, update it through that project's package manager instead. Refresh recorded agent-skill copies separately with `teams-cli skills reinstall` after replacing the package.
+```bash
+teams-cli version --upgrade
+```
+
+Before making changes, the CLI asks the active npm executable for its global package root and verifies that the running package is the `teams-cli` package at that exact location. It then installs the registry's exact selected version without a command shell and refreshes managed agent-skill copies through the newly installed CLI. This prevents a project dependency, another package manager's installation, or a source checkout from being converted into a global npm package. Those installations receive an exact package target and must be updated through their owning package manager and scope.
 
-An npx execution cannot change the persistent notification channel. Request the desired package explicitly instead:
+An npx execution cannot upgrade itself or change the persistent channel. Request the desired package explicitly instead:
 
 ```bash
 npx --prefer-online @michaelschnyder/teams-cli@latest --help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelschnyder/teams-cli",
-  "version": "0.2.0-canary.7.1.g64541e1a",
+  "version": "0.2.0",
   "description": "A safety-conscious CLI for persistent Microsoft Teams sessions",
   "type": "module",
   "bin": {
@@ -66,11 +66,11 @@
     "node": ">=22.20.0"
   },
   "teamsCli": {
-    "channel": "canary",
+    "channel": "stable",
     "releaseSummary": {
-      "title": "Fix canary provenance race after rapid merges",
-      "summary": "## Summary",
-      "url": "https://github.com/michaelschnyder/teams-cli/pull/14"
+      "title": "Teams CLI v0.2.0",
+      "summary": "## Highlights",
+      "url": "https://github.com/michaelschnyder/teams-cli/releases/tag/v0.2.0"
     }
   }
 }