Improve Copilot instructions and agent. Introduce common, useful skills

.github/agents/cve-audit.agent.md

@@ -6,10 +6,12 @@ tools: ["vscode/askQuestions", "execute", "read", "agent/runSubagent", "edit", "
 
 You are a security-focused agent for CVE remediation in the iTwin.js monorepo.
 
+**Prerequisite:** This agent depends on the `cve-remediation` skill for domain knowledge about `pnpm-config.json` structure, fix strategies (direct vs transitive), severity policy, and validation workflows. Ensure that skill is loaded for file structure and fix-ordering guidance.
+
 ## Scope
 
 - Primary target: **Critical** and **High** vulnerabilities from `rush audit`.
-- Fix through dependency updates and `pnpm-config.json` overrides.
+- Fix through dependency updates and `pnpm-config.json` overrides — follow the fix strategy order defined in the `cve-remediation` skill.
 - Keep API compatibility unless explicitly approved otherwise.
 - Use non-interactive commands only.
 
@@ -103,23 +105,13 @@ rush audit --level high
 
    Re-run the audit immediately after `rush update --full`. If High/Critical vulnerabilities are cleared, proceed to Step 4 (verify) — no further manual changes are needed.
 
-3. If High/Critical remain after step 2, **first classify each remaining CVE as direct or transitive**, then remediate using the appropriate path. Do not apply a transitive-fix strategy to a direct CVE, or vice versa.
-
-   **For DIRECT dependency CVEs** (the vulnerable package is a direct dependency of a project package):
-   - **Step D1:** Update the version range of the vulnerable package in the affected `package.json` directly. Run `rush update` and `rush audit --level high`.
-   - **Step D2 (last resort):** If no safe version range exists, add a `globalOverride`. Document why a direct version bump was not viable.
+3. If High/Critical remain after step 2, remediate using the fix strategy defined in the `cve-remediation` skill:
 
-   **For TRANSITIVE dependency CVEs** (the vulnerable package is pulled in by a parent):
-   - **Step T1 — Semver range update (try first):** Update the semver range of the direct parent dependency in the affected `package.json` to a version that resolves the transitive dep to a patched release. Example: if `foo@^1.2.0` pulls in vulnerable `bar@1.0.0` and `bar@1.0.1` is patched, bump `foo` to a range that resolves to `bar >= 1.0.1`. Run `rush update` and `rush audit --level high`.
-   - **Step T2 (last resort):** If no safe parent version resolves the transitive dep, add a `globalOverride`. Document why a semver range update was not viable, including the advisory link and dependency path.
+   - **Classify** each remaining CVE as direct or transitive.
+   - **Direct CVEs:** Update the affected `package.json` version range first. Fall back to `globalOverride` only if no safe version exists.
+   - **Transitive CVEs:** Try semver range update of the parent dependency first. Fall back to `globalOverride` only if no safe parent version exists.
 
-   For `globalOverrides`, add to `common/config/rush/pnpm-config.json`:
-   ```json
-   "globalOverrides": {
-     "<vulnerable-package>": "<patched-version>"
-     // CVE-XXXX-XXXXX: https://advisory-url — <dep-path> — semver fix not viable: <reason>
-   }
-   ```
+   For `globalOverride` and `ignoreCves` syntax and placement, refer to the `cve-remediation` skill's "pnpm-config.json Structure" section. Every override must document why a semver range fix was not viable.
 
 4. Re-resolve and verify after each meaningful change:
 
@@ -138,33 +130,20 @@ rush extract-api
 
 ## Fix Rules
 
+Follow the fix strategy order defined in the `cve-remediation` skill. Key rules:
+
 - For direct dependency CVEs, update the affected package's own `package.json` dependency version range first.
-- For transitive CVEs, use this strict order:
-  1. **Semver range update**: update the direct parent's `package.json` range to a version that resolves the transitive dependency to a patched version.
-  2. **`globalOverrides`**: only if a semver range fix is not viable (e.g., no safe parent version exists, upstream has not released a fix). Document the reason in a comment with the advisory link and dependency path.
-- Never add a `globalOverride` without first documenting why semver range resolution was not sufficient.
-- `ignoreCves` is a last resort for non-production/dev-tooling risk only — with explicit rationale. Add it under the correct nested path in `common/config/rush/pnpm-config.json`:
-  ```json
-  "unsupportedPackageJsonSettings": {
-    "pnpm": {
-      "auditConfig": {
-        "ignoreCves": [
-          "CVE-XXXX-XXXXX" // https://advisory-url — dev-only, no production path — reason
-        ]
-      }
-    }
-  }
-  ```
+- For transitive CVEs: semver range update first, `globalOverride` only as last resort.
+- Never add a `globalOverride` without documenting why semver range resolution was not sufficient.
+- `ignoreCves` is a last resort for non-production/dev-tooling risk only — refer to the `cve-remediation` skill for syntax and placement.
 - Never ignore a Critical/High production-path CVE when a patch is available.
 - `common/config/rush/common-versions.json` is Rush version-consistency policy (`preferredVersions`).
 - If a direct dependency bump triggers Rush consistency errors, update `common/config/rush/common-versions.json` to align versions.
-- If `common-versions.json` changes, commit the generated `common/config/rush/repo-state.json` hash update.
+- If `common/config/rush/common-versions.json` changes, commit the generated `common/config/rush/repo-state.json` hash update.
 
 ## Severity Policy
 
-- **Critical:** Always fix or explicitly document blocker and risk.
-- **High:** Fix unless it requires unacceptable breakage; if deferred, create a tracking issue with risk tradeoff and remediation plan.
-- **Moderate/Low:** Defer and create a tracking issue with recommendation for follow-up.
+Follow the severity policy defined in the `cve-remediation` skill: Critical always fix, High fix unless unacceptable breakage, Moderate/Low defer with tracking issue.
 
 ## Deferral Workflow (Required for Unresolved CVEs)
 

.github/copilot-instructions.md

@@ -41,89 +41,11 @@ iTwin.js is a **monorepo** containing TypeScript packages for creating Infrastru
 - **RPC (Remote Procedure Call)**: For web apps with loosely-coupled frontend/backend over HTTPS. Classes extend `RpcInterface` from `@itwin/core-common`
 - **IPC (Inter-Process Communication)**: For tightly-coupled Electron/mobile apps with stateful connections
 
-### Documentation and Code Examples
+### Packages
 
-The **`example-code/`** directory contains tested code snippets that are automatically extracted into documentation:
+See `rush.json` for the full list of packages and their paths. Key structural areas: `core/` (frontend, backend, common, geometry), `domains/`, `presentation/`, `editor/`, `extensions/`, `tools/`, `ui/`, `utils/`.
 
-- Code examples are marked with special comment blocks: `// __PUBLISH_EXTRACT_START__ ExampleName` and `// __PUBLISH_EXTRACT_END__`
-- Documentation markdown files reference these extracts using `[[include:ExampleName]]` syntax, wrapped inside a multi-line code block
-- This ensures documentation code examples stay in sync with tested, working code
-
-**When generating documentation**: Instead of hardcoding code blocks in markdown files, consider suggesting the user create extraction blocks and reference them in documentation. This maintains consistency and ensures examples remain testable and up-to-date.
-
-### Core Packages
-
-**Foundation (Common to Frontend & Backend):**
-
-- **`@itwin/core-bentley`** (`core/bentley/`): Low-level utilities, logging, events, Id64, GUIDs, and common data structures
-- **`@itwin/core-common`** (`core/common/`): Shared types, RPC interfaces, element/model props, rendering definitions
-- **`@itwin/core-geometry`** (`core/geometry/`): Computational geometry library (curves, surfaces, solids, transformations)
-- **`@itwin/core-quantity`** (`core/quantity/`): Quantity formatting and parsing (units, conversions, display)
-- **`@itwin/core-i18n`** (`core/i18n/`): Internationalization and localization support
-- **`@itwin/core-orbitgt`** (`core/orbitgt/`): Point cloud and reality data processing
-
-**Backend Packages:**
-
-- **`@itwin/core-backend`** (`core/backend/`): Node.js services - IModelDb, elements, models, schemas, native bindings
-- **`@itwin/core-electron`** (`core/electron/`): Electron-specific utilities (ElectronHost, IPC, window management)
-- **`@itwin/core-mobile`** (`core/mobile/`): Mobile platform utilities (iOS/Android RPC, authentication)
-- **`@itwin/express-server`** (`core/express-server/`): Express web server utilities for backend services
-- **`@itwin/ecschema-locaters`** (`core/ecschema-locaters/`): Schema location and loading on backend <!-- Note: "locaters" is the correct package name, even though "locators" is the standard spelling. -->
-- **`@itwin/ecschema-editing`** (`core/ecschema-editing/`): Schema creation and modification APIs
-
-**Frontend Packages:**
-
-- **`@itwin/core-frontend`** (`core/frontend/`): Browser-based visualization - IModelConnection, ViewState, Viewport, rendering
-- **`@itwin/frontend-devtools`** (`core/frontend-devtools/`): Developer tools UI for debugging and diagnostics
-- **`@itwin/frontend-tiles`** (`extensions/frontend-tiles/`): Advanced tile loading and caching strategies
-- **`@itwin/webgl-compatibility`** (`core/webgl-compatibility/`): WebGL feature detection and compatibility checks
-- **`@itwin/core-markup`** (`core/markup/`): SVG-based markup creation and editing for viewports
-- **`@itwin/hypermodeling-frontend`** (`core/hypermodeling/`): 2D/3D drawing sheet integration
-
-**Schema & Metadata:**
-
-- **`@itwin/ecschema-metadata`** (`core/ecschema-metadata/`): EC (Entity-Class) schema management for BIS
-- **`@itwin/ecsql-common`** (`core/ecsql/common/`): ECSQL query types and interfaces
-- **`@itwin/ecschema-rpcinterface-common`** (`core/ecschema-rpc/common/`): RPC interfaces for schema access
-- **`@itwin/ecschema-rpcinterface-impl`** (`core/ecschema-rpc/impl/`): Backend implementation of schema RPC
-
-**Extension & Plugin System:**
-
-- **`@itwin/core-extension`** (`core/extension/`): Extension loading and lifecycle management
-
-**Domain Packages:**
-
-- **`@itwin/analytical-backend`** (`domains/analytical/backend/`): Analytical modeling domain
-- **`@itwin/linear-referencing-backend`** (`domains/linear-referencing/backend/`): Linear referencing for infrastructure
-- **`@itwin/linear-referencing-common`** (`domains/linear-referencing/common/`): Linear referencing shared types
-- **`@itwin/physical-material-backend`** (`domains/physical-material/backend/`): Physical material properties
-
-**Presentation Layer:**
-
-- **`@itwin/presentation-common`** (`presentation/common/`): Rule-driven UI presentation (shared types)
-- **`@itwin/presentation-backend`** (`presentation/backend/`): Presentation rules processing on backend
-- **`@itwin/presentation-frontend`** (`presentation/frontend/`): Presentation data consumption on frontend
-
-**Editing:**
-
-- **`@itwin/editor-common`** (`editor/common/`): Interactive editing shared types
-- **`@itwin/editor-backend`** (`editor/backend/`): Element editing operations on backend
-- **`@itwin/editor-frontend`** (`editor/frontend/`): Interactive editing tools and UI
-
-**Build & Testing Tools:**
-
-- **`@itwin/build-tools`** (`tools/build/`): Build scripts, API extraction, documentation generation
-- **`@itwin/certa`** (`tools/certa/`): Full-stack test runner (Mocha + Chrome/Electron)
-- **`@itwin/perf-tools`** (`tools/perf-tools/`): Performance measurement and profiling
-- **`@itwin/ecschema2ts`** (`tools/ecschema2ts/`): Generate TypeScript from EC schemas
-
-**UI Abstractions:**
-
-- **`@itwin/appui-abstract`** (`ui/appui-abstract/`): Abstract UI component definitions
-
-**Utilities:**
-
-- **`@itwin/workspace-editor`** (`utils/workspace-editor/`): Workspace and settings management
+Documentation code examples live in `example-code/` using extract markers (`__PUBLISH_EXTRACT_START__`/`__PUBLISH_EXTRACT_END__`) referenced in docs via `[[include:ExampleName]]`.
 
 ## Rush Monorepo Workflow
 
@@ -190,36 +112,20 @@ All published packages use **lockstep versioning** (`prerelease-monorepo-lockSte
 
 ## Code Organization Patterns
 
-### Class Registration
-
-Backend entities use registration pattern:
+**Every exported symbol MUST have a release tag** (`@public`, `@beta`, `@alpha`, `@internal`). Missing tags will fail `rush extract-api`.
 
-```typescript
-// In Entity subclass
-public static override get className() { return "MyEntity"; }
-ClassRegistry.register(MyEntity, MyEntity.schema);
-```
-
-### TSDoc Release Tags
+### Internal/Cross-Package Exports
 
-Use release tags consistently - **these determine API stability contracts**:
+Packages use `src/internal/` directories for non-public implementation. Inter-package internal APIs are curated in `src/internal/cross-package.ts` files with inline comments documenting which sibling packages consume them. The ESLint rule `@itwin/no-internal-barrel-imports` enforces this boundary — do not import from internal barrels outside of `cross-package.ts`.
 
-- **`@public`**: Stable public API with strong backward compatibility guarantees. Breaking changes ONLY in major releases
-- **`@beta`**: Public but may change in minor releases. Requires migration documentation
-- **`@alpha`**: Experimental API, may change or be removed. Use with caution
-- **`@internal`**: Private implementation details, not part of API surface, excluded from docs
-- `@packageDocumentation`: Module-level documentation
+### ESLint Configuration
 
-**Every exported symbol MUST have a release tag.** Missing tags will fail the `rush extract-api` check.
+Shared ESLint configs live at `common/config/eslint/` (flat config format). Packages reference these centrally via their lint scripts. Custom rules come from `@itwin/eslint-plugin` (e.g., `@itwin/no-internal-barrel-imports`, deprecation policy enforcement).
 
-### ECSchema and BIS
+### CI Pipelines
 
-iTwin.js uses **EC (Entity-Class)** schemas based on BIS:
-
-- Schema classes in `core/ecschema-metadata`
-- Backend locators in `core/ecschema-locators`
-- Schemas define Elements, Aspects, Relationships, and Models
-- Elements inherit from `Element` base class with required properties: `classFullName`, `code`, `model`
+- GitHub Actions workflows: `.github/workflows/`
+- Azure Pipelines configs: `common/config/azure-pipelines/`
 
 ## Documentation
 
@@ -279,40 +185,10 @@ Valid formats recognized by the ESLint rule:
 
 ## Build Tools
 
-- **`@itwin/build-tools`**: Custom build utilities (`betools` commands)
-  - `betools extract-api`: Generate API reports
-  - `betools docs`: Generate TypeDoc documentation
-- **`@itwin/certa`**: Custom test runner for full-stack tests (Mocha wrapper with Chrome/Electron support)
-- TypeScript compilation: Dual output (CJS in `lib/cjs/`, ESM in `lib/esm/`)
+TypeScript compilation outputs dual format: CJS in `lib/cjs/`, ESM in `lib/esm/`.
 
 ## Common Patterns
 
-### IModelConnection (Frontend) ↔ IModelDb (Backend)
-
-Frontend uses `IModelConnection` (from `@itwin/core-frontend`) to interact with backend `IModelDb` (from `@itwin/core-backend`) via RPC interfaces like `IModelReadRpcInterface`.
-
-### Element Querying
-
-Use ECSQL (ECMAScript SQL dialect) via:
-
-- Backend: `IModelDb.createQueryReader()` or `ECSqlStatement`
-- Frontend: `IModelConnection.createQueryReader()`
-
-### Geometry Handling
-
-`@itwin/core-geometry` provides immutable geometry classes:
-
-- `Point3d`, `Vector3d`, `Range3d` for basic types
-- `CurvePrimitive`, `SolidPrimitive` for complex shapes
-- Use static methods for construction, avoid mutation
-
-## Debugging Tips
-
-1. Use VS Code launch configurations (`.vscode/launch.json`) for package-specific debugging
-2. For frontend tests in browser: Check `vitest.config.mts` for browser provider settings
-3. For RPC debugging: Enable `RpcConfiguration.developmentMode = true`
-4. Native debugging: `@bentley/imodeljs-native` requires Node.js with N-API support
-
 ## Don't Do This
 
 ### Critical - Breaking Changes