#116 Document that container-created virtual environments are not host-portable

[Anonymous]

Originally created by: yablokolabs

Summary

When Atomic creates .venv inside a bind-mounted workspace, its interpreter links and installed binaries belong to the container runtime. After the container exits, the same .venv can be broken on the host—for example, a Python link targeting /usr/local/bin/python3 that does not exist there.

This is finding §14 from Yabloko Labs' evaluation. The behavior is expected from Python environments, but users can reasonably mistake a bind-mounted virtual environment for a portable project artifact.

Current documentation gap

The bundled Docker skill covers container operations but does not explain the portability of runtime-created virtual environments in mounted project directories:

• starter-skills/docker/SKILL.md (github.com)

Atomic cannot reliably intercept every arbitrary python -m venv command or infer every bind mount, so this issue is deliberately scoped to documentation and agent guidance rather than automatic filesystem edits.

Proposed behavior

Extend the Docker skill/container documentation to state that virtual environments and similar interpreter-bound directories are runtime-specific:

• do not assume a container-created .venv can be activated on the host;
• recreate the environment separately in each target runtime;
• recommend ignoring .venv/ in version control, without modifying ignore files unless the user asks;
• identify in the final report whether installation and tests ran in the container or on the host.

Acceptance criteria

• The bundled Docker skill explicitly states that .venv is not generally portable across container and host runtimes.
• The guidance recommends recreating virtual environments per runtime.
• It recommends adding .venv/ to ignore rules but does not edit .gitignore automatically.
• Verification/reporting guidance names the runtime in which installation and tests ran.
• A bind-mounted-project example shows a container-only interpreter path and the host-side recreation step.
• Native non-container workflows do not receive misleading container warnings.

A separate runtime-warning proposal should be opened only if it defines container/bind-mount detection, venv-command interception, opt-out behavior, and false-positive tests.