Document uv migration paths

.ai-context/DECISIONS.md

@@ -50,6 +50,9 @@ architecture discussion.
 - uv support is explicit: `python.manager: uv` opts a project into uv-managed
   setup and `.venv` ownership, while command-level `runner: uv` is independent
   and may be used in composite projects.
+- uv adoption cleanup is manual: when a project moves from Base-managed Python
+  to `python.manager: uv`, Base ignores stale `~/.base.d/<project>/.venv`
+  directories but does not delete them automatically.
 - Build tool provisioning should be profile-driven or project-declared, not
   hardcoded inside `basectl build`.
 - New tool families such as AI developer tools should stay explicit and

docs/README.md

@@ -85,8 +85,8 @@ reference. The filename should answer "what is this about?"
   installers should use Base without moving product-specific logic into Base.
 - [Artifact Adapter Registry](artifact-adapter-registry.md) designs the
   declarative registry and adapter boundary for Base-managed artifacts.
-- [Python Manifest Section](python-manifest.md) records the future structured
-  Python manifest shape and its relationship to current `python-package`
+- [Python Manifest Section](python-manifest.md) records the structured Python
+  manifest shape, uv adoption paths, and its relationship to `python-package`
   artifacts.
 - [Repository Baseline](repo-baseline.md) documents `basectl repo init`,
   `basectl repo check`, `basectl repo configure`, and the optional

docs/python-manifest.md

@@ -34,6 +34,55 @@ environment as the project virtual environment:
 <project-root>/.venv
 ```
 
+## Migration Paths
+
+### Base-Managed Project Adopts uv
+
+For a project that already uses Base's historical project virtual environment,
+add the explicit uv contract to `base_manifest.yaml`:
+
+```yaml
+python:
+  manager: uv
+```
+
+Move Python dependencies into `pyproject.toml`, create or refresh `uv.lock` with
+uv, and run `uv sync` or `basectl setup <project>` from the project root. After
+that, `basectl activate`, `basectl run`, `basectl test`, `basectl build`, and
+`basectl demo` use `<project-root>/.venv` as the project environment unless the
+caller explicitly sets `BASE_PROJECT_VENV_DIR`.
+
+If the old Base-managed environment still exists at
+`~/.base.d/<project>/.venv`, Base reports it as stale and ignores it. Base does
+not delete that directory automatically because it may contain local state,
+debugging context, or artifacts a user still wants. Once `basectl check
+<project>` reports the uv project virtual environment as healthy, users may
+remove the stale Base-managed project environment manually if they no longer
+need it.
+
+### Existing uv Project Adopts Base
+
+For an existing uv project, keep `pyproject.toml`, `uv.lock`, and the repo-local
+`.venv` under uv ownership. Add a small Base manifest that opts into uv-managed
+Python:
+
+```yaml
+project:
+  name: example
+
+python:
+  manager: uv
+```
+
+Run `basectl setup <project>` to let Base delegate Python setup to `uv sync`.
+Add `runner: uv` only for manifest commands that should execute through
+`uv run -- ...`; command runner selection is independent from
+`python.manager: uv`.
+
+Base does not infer uv ownership from `pyproject.toml` or `uv.lock` alone. The
+manifest opt-in is what lets Base choose the repo-local `.venv` and report uv
+diagnostics.
+
 ## Command Runners
 
 Command execution is independent from the project-level Python manager. Any