Update docs

Author: edvilme

api/CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Added the optional `PackageManager.createForProject` factory for package managers whose operations depend on the calling Python project.
+- Added the optional `PackageManager.createForProject` factory for package managers whose operations depend on the calling Python project. Explicit project contexts are used directly; environment-only operations use a scoped manager only when exactly one tracked project matches.
 
 ## [1.4.0]
 

docs/README.md

@@ -1621,6 +1621,44 @@ Reports and changes the packages of an environment.
 | `formatInstallSpec(packageName, version)` | `(packageName: string, version: string) => string` | No | Formats a pinned specifier for this tool, for example `requests==2.31.0` for pip or `requests=2.31.0` for conda. Callers default to `name==version` when absent. |
 | `onDidChangePackages` | `Event<DidChangePackagesEventArgs>` | No | Fire when packages change. |
 
+##### Project-scoped package managers
+
+Implement `createForProject` when package operations depend on project files or
+the process working directory, as they do for tools such as Poetry. Callers that
+already have a `PythonProject` use that project directly. For environment-only
+operations, the extension selects a project-scoped manager only when exactly one
+tracked project uses the environment; it does not choose arbitrarily when no
+project or multiple projects match.
+
+Environment-only command and API paths may still use the originally registered
+manager as an unbound fallback, while package views can suppress operations when
+there is no unique project. Project-sensitive methods on the root manager must
+therefore fail clearly or report that data is unavailable rather than running
+from the extension host's working directory. Keep project-specific caches and
+mutable state on the manager returned by `createForProject`.
+
+```typescript
+class ProjectPackageManager implements PackageManager {
+    readonly name = 'project-pm';
+
+    constructor(private readonly project?: PythonProject) {}
+
+    createForProject(project: PythonProject): PackageManager {
+        return new ProjectPackageManager(project);
+    }
+
+    async manage(
+        environment: PythonEnvironment,
+        options: PackageManagementOptions,
+    ): Promise<void> {
+        if (!this.project) {
+            throw new Error('Package management requires a Python project.');
+        }
+        await runPackageCommand(options, { cwd: this.project.uri.fsPath });
+    }
+}
+```
+
 ```typescript
 class MyPackageManager implements PackageManager {
     readonly name = 'my-pm';

src/types.ts

@@ -721,7 +721,14 @@ export interface PackageManager {
     /**
      * Creates a package manager bound to a Python project.
      *
-     * Project-independent package managers can omit this method.
+     * The extension uses the explicit project supplied by project-based callers. When a caller
+     * provides only an environment, the extension uses a project-bound manager only if exactly
+     * one tracked project uses that environment. The registered root manager may still receive
+     * environment-only operations when no project can be selected safely, so project-sensitive
+     * operations must handle an unbound manager without running in an arbitrary working directory.
+     *
+     * Project-independent package managers can omit this method. Implementations should keep
+     * project-specific caches and mutable state on the returned manager rather than the root.
      *
      * @param project - The project to bind to the package manager.
      * @returns A package manager that uses the project for project-sensitive operations.