cleanup: simplify comments and update docs

Author: eleanorjboyd

.github/instructions/generic.instructions.md

@@ -44,6 +44,7 @@ Provide project context and coding guidelines that AI should follow when generat
 - When using `getConfiguration().inspect()`, always pass a scope/Uri to `getConfiguration(section, scope)` — otherwise `workspaceFolderValue` will be `undefined` because VS Code doesn't know which folder to inspect (1)
 - **path.normalize() vs path.resolve()**: On Windows, `path.normalize('\test')` keeps it as `\test`, but `path.resolve('\test')` adds the current drive → `C:\test`. When comparing paths, use `path.resolve()` on BOTH sides or they won't match (2)
 - **Path comparisons vs user display**: Use `normalizePath()` from `pathUtils.ts` when comparing paths or using them as map keys, but preserve original paths for user-facing output like settings, logs, and UI (1)
-- **Test settings must be set PROGRAMMATICALLY**: Smoke/E2E/integration tests require `python.useEnvironmentsExtension` to be true. Settings.json files alone are unreliable because installed extensions (like ms-python.python) may override with defaults. Use `initializeTestSettings()` from `src/test/initialize.ts` in `suiteSetup()` BEFORE activating the extension — this follows the vscode-python pattern (2)
+- **CI test jobs need webpack build**: Smoke/E2E/integration tests run in a real VS Code instance against `dist/extension.js` (built by webpack). CI jobs must run `npm run compile` (webpack), not just `npm run compile-tests` (tsc). Without webpack, the extension code isn't built and tests run against stale/missing code (1)
+- **Use inspect() for setting checks with defaults from other extensions**: When checking `python.useEnvironmentsExtension`, use `config.inspect()` and only check explicit user values (`globalValue`, `workspaceValue`, `workspaceFolderValue`). Ignore `defaultValue` as it may come from other extensions' package.json even when not installed (1)
 - **API is flat, not nested**: Use `api.getEnvironments()`, NOT `api.environments.getEnvironments()`. The extension exports a flat API object (1)
 - **PythonEnvironment has `envId`, not `id`**: The environment identifier is `env.envId` (a `PythonEnvironmentId` object with `id` and `managerId`), not a direct `id` property (1)

.github/skills/run-e2e-tests/SKILL.md

@@ -73,7 +73,7 @@ E2E tests have system requirements:
 
 - **Python installed** - At least one Python interpreter must be discoverable
 - **Extension builds** - Run `npm run compile` before tests
-- **Test settings** - Tests call `initializeTestSettings()` in `suiteSetup()` to configure `python.useEnvironmentsExtension: true` before activation
+- **CI needs webpack build** - Run `npm run compile` (webpack) before tests, not just `npm run compile-tests` (tsc)
 
 ## Adding New E2E Tests
 

.github/skills/run-integration-tests/SKILL.md

@@ -102,7 +102,7 @@ suite('Integration: [Component A] + [Component B]', function () {
 
 ## Prerequisites
 
-- **Test settings** - Tests call `initializeTestSettings()` in `suiteSetup()` to configure `python.useEnvironmentsExtension: true` before activation
+- **CI needs webpack build** - Run `npm run compile` (webpack) before tests, not just `npm run compile-tests` (tsc)
 - **Extension builds** - Run `npm run compile` before tests
 
 ## Notes

.github/skills/run-smoke-tests/SKILL.md

@@ -117,7 +117,7 @@ suite('Smoke: [Feature Name]', function () {
 
 ## Prerequisites
 
-- **Test settings must be set PROGRAMMATICALLY**: Tests call `initializeTestSettings()` from `src/test/initialize.ts` in `suiteSetup()` to set `python.useEnvironmentsExtension: true` before extension activation. This follows the vscode-python pattern and is more reliable than static settings.json files
+- **CI needs webpack build**: The extension must be built with `npm run compile` (webpack) before tests run. The test runner uses `dist/extension.js` which is only created by webpack, not by `npm run compile-tests` (tsc)
 - **Extension builds**: Run `npm run compile` before tests
 
 ## Notes

src/extension.ts

@@ -1,4 +1,14 @@
-import { commands, ExtensionContext, extensions, l10n, LogOutputChannel, ProgressLocation, Terminal, Uri, window } from 'vscode';
+import {
+    commands,
+    ExtensionContext,
+    extensions,
+    l10n,
+    LogOutputChannel,
+    ProgressLocation,
+    Terminal,
+    Uri,
+    window,
+} from 'vscode';
 import { PythonEnvironment, PythonEnvironmentApi, PythonProjectCreator } from './api';
 import { ENVS_EXTENSION_ID } from './common/constants';
 import { ensureCorrectVersion } from './common/extVersion';
@@ -87,18 +97,14 @@ import { registerPoetryFeatures } from './managers/poetry/main';
 import { registerPyenvFeatures } from './managers/pyenv/main';
 
 export async function activate(context: ExtensionContext): Promise<PythonEnvironmentApi | undefined> {
-    // Use inspect() to check if the user has EXPLICITLY disabled this extension.
-    // Only skip activation if someone explicitly set useEnvironmentsExtension to false.
-    // This ignores defaultValues from other extensions' package.json and defaults to
-    // activating the extension if no explicit setting exists.
+    // Only skip activation if user explicitly set useEnvironmentsExtension to false
     const config = getConfiguration('python');
     const inspection = config.inspect<boolean>('useEnvironmentsExtension');
-    
-    // Check for explicit false values (user deliberately disabled the extension)
-    const explicitlyDisabled = inspection?.globalValue === false || 
-                               inspection?.workspaceValue === false ||
-                               inspection?.workspaceFolderValue === false;
-    
+    const explicitlyDisabled =
+        inspection?.globalValue === false ||
+        inspection?.workspaceValue === false ||
+        inspection?.workspaceFolderValue === false;
+
     const useEnvironmentsExtension = !explicitlyDisabled;
     traceInfo(`Experiment Status: useEnvironmentsExtension setting set to ${useEnvironmentsExtension}`);
     if (!useEnvironmentsExtension) {