docs: align pixi module docs with upstream style

Author: geoHeil

README.md

@@ -17,4 +17,4 @@ colliding with the upstream project name.
 
 | Module | Description |
 |--------|-------------|
-| [`pixi`](./pixi) | Tooling for [Pixi](https://pixi.prefix.dev/latest/)-managed Python projects: verify checked-in `pixi.lock` files, install one or many environments in the same [Dagger](https://dagger.io) container, build filtered runtime images without Pixi, and run commands through Pixi. |
+| [`pixi`](./pixi) | Tooling for [Pixi](https://pixi.prefix.dev/latest/)-managed Python projects: install one or many environments in the same [Dagger](https://dagger.io) container, build filtered runtime images without Pixi, and run commands through Pixi. |

pixi/docs/building.md

@@ -1,50 +1,116 @@
 ---
-icon: lucide/terminal
+icon: lucide/package
 title: Building containers
-description: Install and run Pixi environments inside Dagger containers.
+description: Install Pixi environments in Dagger containers and build runtime images without shipping Pixi itself.
 ---
 
-# Building Containers
+# Building containers
 
-`install` copies the source tree into a Pixi image, mounts Pixi caches, and runs
-`pixi install --locked` for a named environment inside a
-[Dagger](https://dagger.io) container. The returned container is a builder-style
-container and includes the Pixi binary.
+This is the module's core feature: turning a [Pixi](https://pixi.prefix.dev/latest/)
+workspace into a [Dagger](https://dagger.io) container with one or more named
+environments installed.
 
-```python
-from dagger import dag
+Pixi remains responsible for solving, locking, and installing. The module provides
+the Dagger shape around it: source mounting, cache volumes, environment selection,
+Dagger SDK codegen overlays, and runtime images that keep the installed
+`.pixi/envs/*` directories but leave the Pixi binary behind.
 
-ctr = await dag.pixi(source=src).install(environment="default")
-```
+??? abstract "The mental model"
 
-Install more than one environment into the same container:
+    ```mermaid
+    graph LR
+      P["Pixi<br/><i>source tree</i>"] -->|workspace / get_workspaces| WS["PixiWorkspaceSource<br/><i>one per pixi.lock</i>"]
+      P -->|install / run / runtime| Root["Default workspace<br/><i>path = .</i>"]
+      WS -->|install_environments| Builder["Builder container<br/><i>Pixi image</i>"]
+      Builder -->|runtime_environments| Runtime["Runtime container<br/><i>no Pixi binary</i>"]
+    ```
 
-```python
-ctr = await dag.pixi(source=src).install_environments(environments=["default", "docs"])
-```
+    - **`Pixi`** holds your source tree. Its root functions use the workspace at `.`
+      and accept `path` when your Pixi workspace lives deeper in the tree.
+    - **`PixiWorkspaceSource`** is one Pixi workspace rooted at a `pixi.lock`. It is
+      useful when you want to keep a workspace object around explicitly.
+    - **Builder containers** use a Pixi image and can run `pixi install` / `pixi run`.
+    - **Runtime containers** copy selected `.pixi/envs/*` directories and an
+      entrypoint into a fresh image.
 
-Use `run` for one-off commands:
+## `install` - the one-call path
 
-```python
-ctr = await dag.pixi(source=src).run(args=["python", "--version"])
-```
+`install` returns a builder-style container with one Pixi environment installed.
 
-Use `runtime` for a deployable image without Pixi. It installs with Pixi in a
-builder, copies the selected `.pixi/envs/*` directories and a Bash entrypoint
-into a runtime image, and leaves the Pixi binary behind.
+=== "CLI"
 
-```python
-runtime = await dag.pixi(source=src).runtime(environment="default")
-```
+    ```console
+    $ dagger call pixi install --environment default
+    ```
 
-For a final image with several Pixi environments:
+=== "Python SDK"
 
-```python
-runtime = await dag.pixi(source=src).runtime_environments(
-    environments=["default", "model-downloader"],
-    entrypoint_environment="default",
-)
-```
+    ```python
+    from dagger import dag
+
+    ctr = await dag.pixi(source=src).install(environment="default")
+    ```
+
+Use `run` for a one-off command in that environment:
+
+=== "CLI"
+
+    ```console
+    $ dagger call pixi run --args python --args --version
+    ```
+
+=== "Python SDK"
+
+    ```python
+    ctr = await dag.pixi(source=src).run(args=["python", "--version"])
+    ```
+
+## Multiple environments
+
+`install_environments` installs several Pixi environments into the same builder
+container.
+
+=== "CLI"
+
+    ```console
+    $ dagger call pixi install-environments \
+        --environments default \
+        --environments docs
+    ```
+
+=== "Python SDK"
+
+    ```python
+    ctr = await dag.pixi(source=src).install_environments(
+        environments=["default", "docs"],
+    )
+    ```
+
+To install every declared environment, use `install_all_environments`.
+
+## Runtime images
+
+Use `runtime` or `runtime_environments` for deployable images. The module installs
+with Pixi in a builder, copies the selected `.pixi/envs/*` directories and a Bash
+entrypoint into a runtime image, and leaves the Pixi binary behind.
+
+=== "CLI"
+
+    ```console
+    $ dagger call pixi runtime-environments \
+        --environments default \
+        --environments model-downloader \
+        --entrypoint-environment default
+    ```
+
+=== "Python SDK"
+
+    ```python
+    runtime = await dag.pixi(source=src).runtime_environments(
+        environments=["default", "model-downloader"],
+        entrypoint_environment="default",
+    )
+    ```
 
 For a tighter runtime image, copy only the source paths that target needs:
 
@@ -63,22 +129,22 @@ runtime = await dag.pixi(source=src).runtime_environments(
 )
 ```
 
-Use `path` when the Pixi workspace is not at the source root:
+`runtime_source_paths` is source-root-relative and accepts paths or glob patterns.
+For a nested Pixi workspace, include the workspace prefix when needed.
 
-```python
-ctr = await dag.pixi(source=src).install_environments(
-    path="services/api",
-    environments=["default", "docs"],
-)
-```
+## Choosing images
 
-Pixi features become concrete through environments. For example, an environment
-declared with `features = ["docs"]` is installed by passing the environment name,
-not the feature name.
+The default builder image is `ghcr.io/prefix-dev/pixi:0.70.2`, or the concrete
+version resolved from `requires-pixi` when the workspace declares one. Pass
+`pixi_version` or `image` to override it.
 
 The default runtime image is `ubuntu:noble`. Pass `runtime_image` or
-`runtime_base_container` to add operating-system packages before the Pixi
-environments are copied in.
+`runtime_base_container` when the final image needs operating-system packages,
+users, certificates, or another base.
+
+## Dagger modules as dependencies
 
-The default image is `ghcr.io/prefix-dev/pixi:0.70.2`. Pass `image` or
-`pixi_version` to override the builder image.
+If the workspace is itself a Dagger module, the module runs Dagger codegen and
+overlays the generated SDK before installing, so the generated `dagger-io` package
+is present even when `sdk/` is gitignored in CI. This is on by default and is a
+no-op for non-Dagger projects.

pixi/docs/checks/locked.md

@@ -0,0 +1,123 @@
+---
+icon: lucide/box
+title: Environments and features
+description: Use Pixi features to define environments, then install those environments in Dagger containers.
+---
+
+# Environments and features
+
+Pixi features are reusable chunks of project configuration. They can add
+dependencies, PyPI dependencies, tasks, channels, platforms, activation scripts,
+and system requirements. Pixi environments are the named, installable combinations
+of those features.
+
+This module works at the environment level because that is what Pixi installs and
+runs. Define features in `pyproject.toml` or `pixi.toml`, compose them into
+environments, then pass those environment names to Dagger.
+
+## Define environments
+
+```toml
+[tool.pixi.dependencies]
+python = ">=3.13,<3.15"
+
+[tool.pixi.feature.docs.dependencies]
+mkdocs = ">=1.6,<2"
+
+[tool.pixi.feature.model.dependencies]
+pytorch = ">=2.5,<3"
+
+[tool.pixi.environments]
+default = { solve-group = "default" }
+docs = { features = ["docs"], no-default-feature = true }
+model = { features = ["model"] }
+```
+
+In this example:
+
+- `default` installs the base dependencies.
+- `docs` installs only the `docs` feature because `no-default-feature = true`.
+- `model` installs base dependencies plus the `model` feature.
+
+## List environments
+
+=== "CLI"
+
+    ```console
+    $ dagger call pixi environments
+    ```
+
+=== "Python SDK"
+
+    ```python
+    names = await dag.pixi(source=src).environments()
+    ```
+
+For a nested workspace, pass `path`:
+
+```console
+$ dagger call pixi environments --path services/api
+```
+
+## Install several environments
+
+Several environments can live in the same returned container:
+
+=== "CLI"
+
+    ```console
+    $ dagger call pixi install-environments \
+        --environments default \
+        --environments docs \
+        --environments model
+    ```
+
+=== "Python SDK"
+
+    ```python
+    ctr = await dag.pixi(source=src).install_environments(
+        environments=["default", "docs", "model"],
+    )
+    ```
+
+Use `install_all_environments` when the container should include every environment
+declared by the workspace.
+
+## Choose the entrypoint environment
+
+A runtime image may carry several Pixi environments, but its entrypoint activates
+one of them.
+
+```python
+runtime = await dag.pixi(source=src).runtime_environments(
+    environments=["default", "docs", "model"],
+    entrypoint_environment="model",
+)
+```
+
+That image contains `.pixi/envs/default`, `.pixi/envs/docs`, and
+`.pixi/envs/model`. The entrypoint activates `.pixi/envs/model`.
+
+## Features are not installed directly
+
+Do not pass feature names to the module unless an environment has the same name.
+Pixi may define a feature called `docs`, but the install target is the environment
+declared under `[tool.pixi.environments]` or `[environments]`.
+
+```toml
+[tool.pixi.feature.docs.dependencies]
+mkdocs = ">=1.6,<2"
+
+[tool.pixi.environments]
+documentation = { features = ["docs"], no-default-feature = true }
+```
+
+Install `documentation`, not `docs`:
+
+```console
+$ dagger call pixi install --environment documentation
+```
+
+See Pixi's own documentation for the full environment and feature grammar:
+[Pixi environments](https://pixi.prefix.dev/latest/workspace/environment/) and
+[multi-environment workspaces](https://pixi.prefix.dev/latest/workspace/multi_environment/).