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

.github/copilot-instructions.md

@@ -1,13 +1,57 @@
 # Copilot Instructions for vscode-powershell
 
-## Updating NPM Packages
-
-- Read [docs/development.md](../docs/development.md) "Tracking Upstream Dependencies" first
-- Dependencies are split: `dependencies` + `devDependencies` for build, `optionalDependencies` for lint/test
-- Remember to use `npm install --include=optional` since we also need to update lint and test dependencies
-- The `.npmrc` uses an Azure Artifacts mirror; read its comments for authentication instructions
-- After updating, verify: `npm run compile` (build), `npm run lint` (lint), `npm audit` (security)
-- The ESLint packages (`eslint`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`) should be updated together
-- 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
+This is the VS Code extension for PowerShell — an LSP client that communicates with
+[PowerShellEditorServices][] (PSES), the LSP server. The extension manages the PSES process
+lifecycle, 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
+```
+
+After any code change, always run `npm run compile`, `npm run lint`, and `npm run format`. Tests run inside a VS Code Insiders instance — there is no way to run a
+single test from the command line. Tests live in `test/` mirroring `src/` structure and use
+Mocha BDD (`describe`/`it`).
+
+## Architecture
+
+`activate()` in `src/extension.ts` creates the `Logger`, `SessionManager`, and two groups of
+features:
+
+1. **Standalone features** — commands that don't need the LSP client (e.g. `PesterTestsFeature`)
+2. **LanguageClientConsumers** — features extending `LanguageClientConsumer` that depend on the
+   LSP client and override `onLanguageClientSet()` to register their handlers
+
+`SessionManager` (`src/session.ts`) owns the full lifecycle: finding a PowerShell executable
+(`src/platform.ts`), spawning PSES (`src/process.ts`), connecting the `LanguageClient`, and
+restarting on critical setting changes.
+
+Each feature in `src/features/` exports one `vscode.Disposable` class. Custom LSP message
+types are defined as `RequestType`/`NotificationType` constants in the same file.
+`IPowerShellExtensionClient` in `src/features/ExternalApi.ts` is the public API for other
+extensions.
+
+### PSES and Cross-Repo Work
+
+The `modules/` folder contains the PSES, PSReadLine, and PSScriptAnalyzer PowerShell modules. In development it is a
+symlink to `../PowerShellEditorServices/module` — [PowerShellEditorServices][] must be
+cloned as a sibling and built before `npm run compile` will succeed. For cross-repo work, use `pwsh-extension-dev.code-workspace`.
+
+## Key Conventions
+
+- **VS Code best practices**: Follow the [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 and prefer disposable patterns for lifecycle management.
+- **Logging**: Use `ILogger` (not `console.log`). Tests use `TestLogger` from `test/utils.ts`.
+- **Settings**: Defined in `package.json` under `contributes.configuration`, read via
+  `vscode.workspace.getConfiguration("powershell")` at point of use. Helpers in `src/settings.ts`.
+- **TypeScript**: Strict mode, ESNext, `verbatimModuleSyntax`. `explicit-function-return-type`
+  enforced. Unused vars prefixed `_`. Formatting via Prettier with the `organize-imports`
+  plugin. Use `import x = require("x")` for Node/VS Code built-ins.
+- **File headers**: Every source file starts with `// Copyright (c) Microsoft Corporation.`
+  and `// Licensed under the MIT License.`

.github/skills/release/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: release
+description: >
+    Guide for preparing a release of the PowerShell VS Code extension. Use when
+    asked to prepare a release, update the version, or create a release PR.
+---
+
+# Release Process
+
+Read [docs/development.md](../../../docs/development.md) "Creating a Release" and "Versioning" sections first.
+
+## Agent-Actionable Steps (1–2)
+
+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 and open a PR to `main` on GitHub.
+
+## Manual Steps (3–4)
+
+These require Azure DevOps access and cannot be performed by an agent:
+
+3. After merge, push `main` to the Azure DevOps remote (`ado HEAD:upstream`) to trigger signing pipelines.
+4. Download and test assets from draft GitHub Releases, then publish.

.github/skills/update-npm-packages/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: update-npm-packages
+description: >
+    Guide for updating NPM dependencies in vscode-powershell. Use when asked to
+    update packages, fix vulnerabilities, or bump dependency versions.
+---
+
+# Updating NPM Packages
+
+Read [docs/development.md](../../../docs/development.md) "Tracking Upstream Dependencies"
+section for full context.
+
+## Rules
+
+- Dependencies are split into three groups:
+    - `dependencies` — runtime packages bundled into the extension
+    - `devDependencies` — build tools only (minimum for Azure DevOps pipeline)
+    - `optionalDependencies` — lint, type-checking, and test tools (for development and GitHub Actions)
+- Always use `npm install --include=optional` to get all three groups.
+- The `.npmrc` uses an Azure Artifacts mirror; read its comments for authentication instructions.
+- When updating `engines.vscode` follow the "Tracking Upstream Dependencies" section of `docs/development.md`.
+- Update the ESLint packages (`eslint`, `@eslint/js`, `typescript-eslint`,
+  `eslint-config-prettier`) together and fix any new lint warnings.
+- After updating, verify: `npm run compile`, `npm run lint`, `npm audit`.
+- For vulnerabilities in transitive dependencies identified by `npm audit`, add an `overrides` entry in `package.json`
+  rather than using `npm audit fix --force` which may downgrade our packages.
+- Check that each `overrides` entry is still necessary.