docs: address PR review feedback on API manual

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

Copilot-Session: 2f79caeb-d789-4eb6-898b-4bddd9d3292a

Author: edvilme

api/README.md

@@ -35,3 +35,20 @@ export async function activate() {
 }
 ```
 
+## Full API reference
+
+📘 **[Python Environments API reference](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md)**
+
+The complete manual documents every method and data type, organized by domain -
+environments, packages, projects, execution, environment variables, and
+extensibility - with field tables, parameter tables, return types, and examples.
+
+- [Environments](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#environments) - discover, resolve, select, create, and remove interpreters
+- [Packages](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#packages) - list, install, uninstall, and look up versions
+- [Projects](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#projects) - the folders the extension tracks
+- [Execution](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#execution) - run Python in terminals, tasks, and background processes
+- [Environment variables](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#environment-variables) - resolved variables for a scope
+- [Extensibility](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#extensibility) - register your own environment manager, package manager, or project creator
+
+See [`CHANGELOG.md`](https://github.com/microsoft/vscode-python-environments/blob/main/api/CHANGELOG.md) for API changes between versions.
+

docs/README.md

@@ -379,12 +379,17 @@ refreshEnvironments(scope: RefreshEnvironmentsScope): Promise<void>;
 | --- | --- | --- | --- |
 | `scope` | [`RefreshEnvironmentsScope`](#scope-types) | Yes (may be `undefined`) | `Uri` refreshes discovery for that project or folder; `undefined` refreshes global and workspace discovery. |
 
-**Returns** `Promise<void>`, resolving when discovery completes. Results arrive
-through [`onDidChangeEnvironments`](#ondidchangeenvironments); subscribe before
-refreshing if you need the deltas.
+**Returns** `Promise<void>`, resolving when the managers finish discovery.
+
+Read the results with [`getEnvironments`](#getenvironments) once the promise
+settles. Do not rely on [`onDidChangeEnvironments`](#ondidchangeenvironments)
+to deliver them: that event is optional on `EnvironmentManager`, and
+`refreshEnvironments` does not synthesize one, so whether a refresh produces
+deltas is up to the provider.
 
 ```typescript
 await api.refreshEnvironments(undefined);
+// Authoritative: read the list rather than waiting for an event.
 const refreshed = await api.getEnvironments('all');
 ```
 
@@ -439,6 +444,29 @@ const active = await api.getEnvironment(
 );
 ```
 
+> [!IMPORTANT]
+> **This call can return a stale value.** It is deliberately non-blocking: it
+> races the real resolution against a one-second timeout so that slow initial
+> discovery cannot stall callers. If resolution has not finished in time, it
+> returns the *last-known* environment for the scope - which may be `undefined`
+> on a first call - while resolution continues in the background.
+>
+> The resolved value is published through
+> [`onDidChangeEnvironment`](#ondidchangeenvironment) once it settles. If your
+> feature needs the authoritative selection, subscribe to that event and treat
+> the value from `getEnvironment` as a fast first guess:
+>
+> ```typescript
+> let current = await api.getEnvironment(projectUri); // May be last-known.
+> context.subscriptions.push(
+>     api.onDidChangeEnvironment((e) => {
+>         if (e.uri?.toString() === projectUri.toString()) {
+>             current = e.new; // Authoritative once resolution settles.
+>         }
+>     }),
+> );
+> ```
+
 #### `setEnvironment`
 
 Selects - or clears - the environment for one or more scopes, and persists the
@@ -1236,15 +1264,15 @@ const module: PythonTerminalExecutionOptions = {
 | `name` | `string` | Yes | Name of the task, shown in the task UI. |
 | `args` | `string[]` | Yes | Arguments passed to the Python executable. |
 | `project` | [`PythonProject`](#pythonproject) | No | Project the task belongs to. |
-| `cwd` | `string` | No | Working directory. Defaults to the project directory of the script being run. |
+| `cwd` | `string` | No | Working directory for the task's shell execution. When omitted, VS Code resolves it from the task scope - the workspace folder containing `project`, or the global scope when `project` is not supplied. |
 | `env` | `{ [key: string]: string }` | No | Additional environment variables for the task. |
 
 #### `PythonBackgroundRunOptions`
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `args` | `string[]` | Yes | Arguments passed to the Python executable. |
-| `cwd` | `string` | No | Working directory. Defaults to the project directory of the script being run. |
+| `cwd` | `string` | No | Working directory, passed straight to the spawned process. When omitted, the process inherits the extension host's working directory, which is **not** your project folder - always supply `cwd` (for example `project.uri.fsPath`) if the script resolves relative paths. |
 | `env` | `{ [key: string]: string \| undefined }` | No | Additional environment variables. An `undefined` value unsets a variable. |
 
 #### `PythonProcess`
@@ -1391,11 +1419,20 @@ runInBackground(
 | Parameter | Type | Required | Description |
 | --- | --- | --- | --- |
 | `environment` | [`PythonEnvironment`](#pythonenvironment) | Yes | Environment used to start the process. |
-| `options` | [`PythonBackgroundRunOptions`](#pythonbackgroundrunoptions) | Yes | `args` for Python, plus optional `cwd` and `env`. |
+| `options` | [`PythonBackgroundRunOptions`](#pythonbackgroundrunoptions) | Yes | `args` for Python, plus optional `cwd` and `env`. Supply `cwd` - it is not inferred. |
 
 **Returns** `Promise<PythonProcess>` with `stdin`, `stdout`, `stderr`, `kill()`,
 and `onExit()`.
 
+> [!IMPORTANT]
+> `cwd` is forwarded to the spawned process unchanged. There is no project
+> context to infer it from, so when you omit it the process inherits the
+> extension host's working directory rather than your project folder. Pass
+> `cwd` explicitly whenever the script resolves relative paths.
+>
+> You own the process lifetime: call `kill()` when your feature is done, and
+> tie it to your disposables so it does not outlive deactivation.
+
 ```typescript
 const proc = await api.runInBackground(env, {
     args: ['-c', 'import sys; print(sys.version)'],

src/types.ts

@@ -1423,7 +1423,9 @@ export interface PythonBackgroundRunOptions {
     args: string[];
 
     /**
-     * Current working directory for the script or module. Default is the project directory for the script being run.
+     * Current working directory for the script or module. This is passed directly to the spawned
+     * process; when it is omitted the process inherits the extension host's working directory,
+     * which is not the project directory. Supply this when the script resolves relative paths.
      */
     cwd?: string;