docs: add @remarks to EnvironmentManager interface documenting when each method is called

[StellaHuang95]

Summary

Adds @remarks JSDoc sections to all methods on the EnvironmentManager interface, documenting which user actions or internal events trigger each method. Changes are documentation-only — no functional changes.

Motivation

Raised in #378: third-party extension authors implementing EnvironmentManager know what each method does (the existing JSDoc covers that), but not when or why it gets called. For example, get() is described as "retrieves the current Python environment" — but there's no mention that it's called at extension startup, during terminal activation, before script execution, etc.

This makes it hard for authors to reason about their implementation. They end up guessing at lifecycle behavior, which leads to bugs (e.g., not caching in get() because they didn't realize it's called frequently).

What's added

@remarks sections on 8 methods of EnvironmentManager in both src/api.ts and pythonEnvironmentsApi/src/main.ts:

Method	Trigger summary
create	"Create Environment" command, "+" button in tree view, new package project wizard
remove	Right-click → "Delete Environment" in tree view
refresh	Refresh button in the Python Environments view title bar
getEnvironments	Tree view expansion, environment picker, internally after refresh
set	Environment picker selection, checkmark button in tree view, auto-select after create, startup caching, project removal
get	Startup, after set, terminal activation, script execution, picker display, auto-discovery
resolve	File picker interpreter selection, defaultInterpreterPath resolution, pre-run resolution
clearCache	"Python: Clear Cache" command

Each remark was verified by tracing every call site through InternalEnvironmentManager → envManagers.ts → envCommands.ts → extension.ts command registrations and package.json menu contributions.

Who this helps

Extension authors building environment managers for tools like Hatch, Pixi, uv, etc. They can now hover over any EnvironmentManager method in their IDE and see exactly what user actions will invoke it, making implementation decisions much clearer.

Files changed

• src/api.ts — internal API copy (+45 lines, documentation only)
• pythonEnvironmentsApi/src/main.ts — published API package (+45 lines, documentation only)

Refs #378