Problem description

Hi,

I think that the documentation is missing a high level overview of the "inner workings" of pixi, as the current Basic usage section goes directly from pixi add to pixi run. It can be helpful both to understand when something is not working as expected and to showcase every manual step that pixi run avoids.

I would include something along the lines that a pixi project consist of 3 things: pixi.toml, pixi.lock, .pixi/.

• pixi add adds dependencies to pixi.toml,
• pixi lock resolves dependencies to a particular version and records them in pixi.lock,
• pixi install takes pixi.lock and installs those dependencies into an environment in the .pixi/ directory.
• pixi run <command> activates the environment and runs the command.

And, then, to note that pixi run automatically runs pixi install if it hasn't been done. And pixi install would run pixi lock if it hasn't been done as well. Maybe this could be shown as a graph of commands (as pixi shell also runs pixi install, and so on).

I just had to explain this "inner working" to a co-worker which was using the Python extension from VSCode. There, the "Run file" button calls directly .pixi/envs/.../python file.py, bypassing pixi run, and would not install newly added packages with pixi add.

If I have some spare time, I can try contributing this piece of documentation, if you think it would be helpful.