docs: imported @currentEnv and Python Homebrew re-exec

packages/varlock-website/src/content/docs/guides/environments.mdx

@@ -22,7 +22,7 @@ That said, as a first step to adopting `varlock`, you could rely entirely on pro
 
 ### Loading environment-specific `.env` files
 
-Any environment-specific files (e.g., `.env.development`) will automatically be loaded if they match the value of the _current environment_ as set by the [`@currentEnv`](/reference/root-decorators/#currentenv) root decorator in your `.env.schema` file.
+Any environment-specific files (e.g., `.env.development`) will automatically be loaded if they match the value of the _current environment_ as set by the [`@currentEnv`](/reference/root-decorators/#currentenv) root decorator in your `.env.schema` file. The referenced flag item can be defined in that same file or brought in by [`@import`](/guides/import/).
 
 The files are applied with a specific precedence (increasing):
 - `.env.schema` - your schema file, which can also contain default values

packages/varlock-website/src/content/docs/guides/monorepos.mdx

@@ -55,7 +55,7 @@ Imports must flow in one direction. If `web` imports `api` and `api` also import
 :::
 
 :::note[Shared environment flag]
-If several projects share an environment flag like `APP_ENV`, define it in the shared schema and import it. For per-service environment variations, see [Loading environment-specific `.env` files](/guides/environments#loading-environment-specific-env-files).
+If several projects share an environment flag like `APP_ENV`, define it in the shared schema and import it. A package can then set `# @currentEnv=$APP_ENV` and `pick` that key; the flag does not have to be redefined in the package schema. For per-service environment variations, see [Loading environment-specific `.env` files](/guides/environments#loading-environment-specific-env-files).
 :::
 
 ### Pointing varlock at the right directory

packages/varlock-website/src/content/docs/integrations/python.mdx

@@ -62,6 +62,39 @@ varlock run -- poetry run pytest
 varlock run -- python manage.py runserver
 ```
 
+### Auto-invoking `varlock run` from Python
+
+Some scripts re-exec themselves under `varlock run` so callers do not have to wrap every invocation. Check [`__VARLOCK_RUN`](/reference/reserved-variables/#__varlock_run) first so you do not recurse:
+
+```python
+import os
+import sys
+
+if "__VARLOCK_RUN" not in os.environ:
+    os.execv("varlock", ["varlock", "run", "--", sys.executable] + sys.argv)
+```
+
+`varlock run` passes through the executable path it is given. On Linux that pattern is usually fine. On macOS with Homebrew Python, `sys.executable` is the fully resolved Cellar binary, not the venv symlink. Re-execing that path means PEP 405 never finds `pyvenv.cfg`, so the child leaves the venv and the script fails in ways that look like a varlock problem.
+
+Rebuild the venv's `python` path instead:
+
+```python
+import os
+import sys
+
+if "__VARLOCK_RUN" not in os.environ:
+    venv = os.environ.get("VIRTUAL_ENV")
+    if venv:
+        python = os.path.join(venv, "bin", "python3")
+    elif sys.prefix != sys.base_prefix:
+        python = os.path.join(sys.prefix, "bin", "python3")
+    else:
+        python = sys.executable
+    os.execv("varlock", ["varlock", "run", "--", python] + sys.argv)
+```
+
+On Windows, use `Scripts\\python.exe` under the venv prefix instead of `bin/python3`.
+
 :::caution[Shell expansion]
 Environment variables in the command itself are expanded by your shell **before** varlock runs. Pass overrides on the left (`APP_ENV=production varlock run -- …`) or use [`varlock printenv`](/reference/cli/load-and-run/#printenv) to read resolved values into the shell.
 :::

packages/varlock-website/src/content/docs/reference/reserved-variables.mdx

@@ -82,7 +82,7 @@ The serialized env graph (resolved config values plus metadata) injected by [`va
 
 ### `__VARLOCK_RUN`
 
-A marker set so a child process can detect that it is running under `varlock run`.
+A marker set so a child process can detect that it is running under `varlock run`. Scripts that re-exec themselves under `varlock run` should check this first so they do not recurse. On macOS with Homebrew Python, do not pass `sys.executable` into that re-exec: see [Auto-invoking varlock run from Python](/integrations/python/#auto-invoking-varlock-run-from-python).
 
 ### `__VARLOCK_EXECUTION_PHASE`