Update copilot-instructions.md with architecture, conventions, and release process

Add comprehensive guidance for AI agents including build/lint/test commands,
extension architecture (SessionManager, LanguageClientConsumer pattern, features),
key conventions (ILogger, settings access, TypeScript style), versioning and
release process (even/odd minor scheme, updateVersion.ps1), and cross-repo
PSES relationship.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: andyleejordan

.github/copilot-instructions.md

@@ -1,5 +1,123 @@
 # Copilot Instructions for vscode-powershell
 
+## Overview
+
+This is the VS Code extension for PowerShell — it is a Language Server Protocol (LSP) client
+that communicates with [PowerShellEditorServices][] (PSES), the LSP server. The extension
+manages the lifecycle of the PSES process, provides UI features, and handles debugging.
+
+[PowerShellEditorServices]: https://github.com/PowerShell/PowerShellEditorServices
+
+## Build, Lint, and Test
+
+```sh
+npm install --include=optional  # Install all deps (lint/test tools are in optionalDependencies)
+npm run compile          # Build with esbuild (outputs to dist/)
+npm run lint             # ESLint (strict TypeScript-aware rules)
+npm run format           # Prettier check (with organize-imports plugin)
+npm test                 # Integration tests via @vscode/test-cli (launches VS Code Insiders)
+```
+
+After any code change, always run `npm run compile`, `npm run lint`, and `npm run format` to
+catch build errors, lint violations, and formatting issues before committing.
+
+There is no way to run a single test from the command line; the test suite runs inside a VS
+Code instance via `@vscode/test-cli` and uses Mocha BDD (`describe`/`it`). Tests live in
+`test/` mirroring `src/` structure (`test/core/`, `test/features/`). The test config is in
+`.vscode-test.mjs`.
+
+## Architecture
+
+### Extension Activation (`src/extension.ts`)
+
+`activate()` creates the `Logger`, `SessionManager`, and two groups of features:
+
+1. **Standalone features** — registered as commands, don't need the language client (e.g.
+   `PesterTestsFeature`, `CodeActionsFeature`, `ExamplesFeature`)
+2. **LanguageClientConsumers** — features that depend on the LSP client (e.g.
+   `ConsoleFeature`, `DebugSessionFeature`, `ShowHelpFeature`)
+
+### Session Management (`src/session.ts`)
+
+`SessionManager` owns the full lifecycle: finding a PowerShell executable (`src/platform.ts`),
+spawning the PSES process (`src/process.ts` via `PowerShellProcess`), connecting the
+`LanguageClient`, and restarting on critical setting changes. It distributes the language
+client to all `LanguageClientConsumer` instances.
+
+### LanguageClientConsumer Pattern (`src/languageClientConsumer.ts`)
+
+All features that need the LSP client extend the abstract `LanguageClientConsumer` class. It
+provides a shared promise-based mechanism (`getLanguageClient()`) to wait for the client to
+start, with a cancellable progress notification. Subclasses override `onLanguageClientSet()`
+to register their LSP handlers.
+
+### Feature Modules (`src/features/`)
+
+Each file typically exports one class implementing `vscode.Disposable`. Features register VS
+Code commands, event handlers, or LSP request/notification handlers. Custom LSP message types
+are defined as `RequestType`/`NotificationType` constants in the same file.
+
+### External API (`src/features/ExternalApi.ts`)
+
+The `IPowerShellExtensionClient` interface is the public API other VS Code extensions use to
+interact with this extension (register, wait for start, get version details).
+
+### Bundled Modules (`modules/`)
+
+Contains vendored PowerShell modules (PSES, PSReadLine, PSScriptAnalyzer) that ship with the
+extension. For local development, the [PowerShellEditorServices][] repo is cloned as a
+sibling directory (`../PowerShellEditorServices`). Changes to LSP messages, server-side
+features, or the debugger adapter require work in that repo — this extension is only the
+client side. For cross-repo work, use the multi-root workspace
+`pwsh-extension-dev.code-workspace` which includes both repositories.
+
+## Key Conventions
+
+- **VS Code extension best practices**: Follow the
+  [VS Code Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines)
+  and [UX Guidelines](https://code.visualstudio.com/api/ux-guidelines/overview). Use VS Code's
+  APIs idiomatically (e.g. `vscode.window` for UI, `vscode.workspace` for configuration,
+  disposable patterns for lifecycle management).
+- **Logging**: Use the `ILogger` interface (not `console.log`). The concrete `Logger` class
+  wraps a VS Code `LogOutputChannel`. Tests use `TestLogger` from `test/utils.ts`.
+- **Settings**: Settings are defined in `package.json` under `contributes.configuration` and
+  read via `vscode.workspace.getConfiguration("powershell")` at point of use. Helper functions
+  (`changeSetting`, `validateCwdSetting`, `getChosenWorkspace`) live in `src/settings.ts`.
+- **TypeScript style**: Strict mode, ESNext target, `verbatimModuleSyntax`. ESLint enforces
+  `explicit-function-return-type`. Unused vars prefixed with `_`. Formatting via Prettier
+  with the `organize-imports` plugin.
+- **Import style**: Uses TypeScript `import x = require("x")` for Node/VS Code built-ins
+  alongside ESM-style `import` for other modules.
+- **File headers**: Every source file starts with `// Copyright (c) Microsoft Corporation.`
+  and `// Licensed under the MIT License.`
+
+## Versioning and Release Process
+
+The extension version follows `vYYYY.X.Z` (year, minor, patch) — not semver. Releases are
+based on completed work, not a schedule. Key rules:
+
+- **Even minor** = release (e.g. `v2026.2.0`), **odd minor** = pre-release (e.g. `v2026.3.0-preview`)
+- A release's version is `n-1` of its preview: release `v2026.2.0` is previewed by `v2026.3.0-preview`
+- This ensures the marketplace always shows a pre-release option (odd > even by version sort)
+- The `preview` field in `package.json` is **always `false`** — even for pre-releases
+- Append `-preview` to the version in the changelog and Git tag, but **not** in `package.json`
+  (the marketplace ignores pre-release suffixes)
+- For multiple pre-releases, increment patch: `v2026.3.0-preview`, `v2026.3.1-preview`, etc.
+- PSES version must **not** change between a pre-release and its subsequent release
+
+### Release Steps
+
+1. Use `./tools/updateVersion.ps1 -Version "<version>" -Changes "<summary>"` in both repos
+   (PSES first, then vscode-powershell). The script validates even/odd rules, updates
+   `package.json` version, prepends a changelog entry (auto-including the PSES version from
+   `../PowerShellEditorServices`), and creates a commit.
+2. Push to an ephemeral `release` branch, open and merge a PR to `main`.
+3. After merge, push `main` to the Azure DevOps remote (`ado`) to trigger signing pipelines.
+4. Download and test assets from draft GitHub Releases, then publish.
+
+PowerShellEditorServices uses standard semver (`vX.Y.Z`). Git tags (`vX.Y.Z`) mark releases;
+the `release` branch is ephemeral and deleted after each release.
+
 ## Updating NPM Packages
 
 - Read [docs/development.md](../docs/development.md) "Tracking Upstream Dependencies" first
@@ -11,3 +129,5 @@
 - Fix any new lint warnings from updates to ESLint
 - Use `npm audit` to identify vulnerabilities
 - Do not use `npm audit fix --force` when a vulnerability is in a transitive dependency, instead add an `overrides` entry
+- When `engines.vscode` is updated, `@types/vscode` must match (using `~` not `^`), and
+  `@types/node` major must match the Node.js version in VS Code's Electron