diff --git a/docs/first_project.md b/docs/first_project.md
new file mode 100644
index 0000000000..8704dce712
--- /dev/null
+++ b/docs/first_project.md
@@ -0,0 +1,153 @@
+# Making a Pixi project
+
+Pixi's biggest strength is its ability to create reproducible powerful and flexible projects.
+Let's go over the common steps to create a Pixi project.
+
+## Creating a Pixi project
+To create a new Pixi project, you can use the `pixi init` command:
+
+```shell
+pixi init my_project
+```
+
+This command creates a new directory called `my_project` with the following structure:
+
+```shell
+my_project
+├── .gitattributes
+├── .gitignore
+└── pixi.toml
+```
+
+The `pixi.toml` file is the manifest of your Pixi project.
+It contains all the information about your project, such as its channels, platforms, dependencies, tasks, and more.
+
+The one created by `pixi init` is a minimal manifest that looks like this:
+
+```toml title="pixi.toml"
+[workspace]
+authors = ["Jane Doe <jane.doe@example.com>"]
+channels = ["conda-forge"]
+name = "my_project"
+platforms = ["osx-arm64"]
+version = "0.1.0"
+
+[tasks]
+
+[dependencies]
+```
+
+??? tip "Do you want autocompletion of the manifest file?"
+    As `pixi.toml` has a JSON schema, it is possible to use IDE’s like VSCode to edit the field with autocompletion.
+    Install the Even [Better TOML VSCode](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension to get the best experience.
+    Or use the integrated schema support in PyCharm.
+
+## Managing dependencies
+After creating the project, you can start adding dependencies to the project.
+Pixi uses the `pixi add` command to add dependencies to the project.
+This command will , by default, add the **conda** dependency to the `pixi.toml`, solve the dependencies, write the lockfile and install the package in the environment.
+For example, lets add `numpy` and `pytest` to the project.
+
+```shell
+pixi add numpy pytest
+```
+This results in these lines being added:
+
+```toml title="pixi.toml"
+[dependencies]
+numpy = ">=2.2.6,<3"
+pytest = ">=8.3.5,<9"
+```
+
+You can also specify the version of the dependency you want to add.
+
+```shell
+pixi add numpy==2.2.6 pytest==8.3.5
+```
+
+### PyPI dependencies
+Pixi normally uses `conda` packages for dependencies, but you can also add dependencies from PyPI.
+Pixi will make sure it doesn't try to install the same package from both sources, and avoid conflicts between them.
+
+If you want to add them to your project you can do that with the `--pypi` flag:
+
+```shell
+pixi add --pypi requests
+```
+This will add the `requests` package from PyPI to the project:
+
+```toml title="pixi.toml"
+[pypi-dependencies]
+requests = ">=2.31.0,<3"
+```
+
+## Lockfile
+Pixi will always create a lockfile when the dependencies are solved.
+This file will contain all the exact version of the packages and their dependencies.
+Resulting in a reproducible environment, that you can share with others or use for testing and deployment.
+
+The lockfile is called `pixi.lock` and it is created in the root of the project.
+It contains all the information about the dependencies, such as their versions, channels, platforms, and more.
+
+```yaml title="pixi.lock"
+version: 6
+environments:
+  default:
+    channels:
+    - url: https://prefix.dev/conda-forge/
+    indexes:
+    - https://pypi.org/simple
+    packages:
+      osx-arm64:
+      - conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda
+      - pypi: ...
+packages:
+- conda: https://prefix.dev/conda-forge/osx-arm64/bzip2-1.0.8-h99b78c6_7.conda
+  sha256: adfa71f158cbd872a36394c56c3568e6034aa55c623634b37a4836bd036e6b91
+  md5: fc6948412dbbbe9a4c9ddbbcfe0a79ab
+  depends:
+  - __osx >=11.0
+  license: bzip2-1.0.6
+  license_family: BSD
+  size: 122909
+  timestamp: 1720974522888
+- pypi: ...
+```
+
+## Managing tasks
+Pixi has a built-in cross-platform task runner that allows you to define tasks in the manifest.
+This is a great way to share tasks with others and to ensure that the same tasks are run in the same environment.
+The tasks are defined in the `pixi.toml` file under the `[tasks]` section.
+
+You can add one to your project by running the `pixi task add` command.
+
+```shell
+pixi task add hello "echo Hello, World!"
+```
+This will add the following lines to the `pixi.toml` file:
+
+```toml title="pixi.toml"
+[tasks]
+hello = "echo Hello, World!"
+```
+You can then run the task using the `pixi run` command:
+
+```shell
+pixi run hello
+```
+This will execute the command `echo Hello, World!` in the environment.
+
+## Environments
+Pixi always creates a virtual environment for your project.
+These environments are located in the `.pixi/envs` directory in the root of your project.
+
+Using these environments is as simple as running the `pixi run` or `pixi shell` command.
+These commands will automatically activate the environment and run the command in it.
+
+```shell
+pixi run python -VV
+# or:
+pixi shell
+python -VV
+exit
+```
diff --git a/docs/getting_started.md b/docs/getting_started.md
index d0f98291e0..351083bd06 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -1,112 +1,106 @@
-Every Pixi workspace is described by a Pixi manifest.
-In this simple example we have a single task `start` which runs a Python file and two dependencies, `cowpy` and `python`.
+# Basic usage of Pixi
 
-```toml title="pixi.toml"
---8<-- "docs/source_files/pixi_workspaces/introduction/task_add/pixi.toml"
-```
+Pixi can do alot of things, but it is designed to be simple to use.
+Let's go through the basic usage of Pixi.
 
-`channels` describes where our dependencies come from and `platforms` which platforms we support.
-However, you might wonder why we need to specify the platforms if Pixi could just extract this information from your operating system.
-That is because every dependency in your environment is stored in the lockfile called `pixi.lock`.
-This ensures that even if you run your workspace on a different platform, the environment will contain exactly the dependencies that were solved on your machine.
-This is one of the core features that makes Pixi reproducible.
-Learn more about lock files in [this chapter](./workspace/lockfile.md).
+## Managing workspaces or projects
 
+- [`pixi init`](./reference/cli/pixi/init.md) - create a new Pixi manifest in the current directory
+- [`pixi add`](./reference/cli/pixi/add.md) - add a dependency to your manifest
+- [`pixi remove`](./reference/cli/pixi/remove.md) - remove a dependency from your manifest
+- [`pixi update`](./reference/cli/pixi/update.md) - update dependencies in your manifest
+- [`pixi upgrade`](./reference/cli/pixi/upgrade.md) - upgrade the dependencies in your manifest to the latest versions, even if you pinned them to a specific version
+- [`pixi lock`](./reference/cli/pixi/lock.md) - create or update the lockfile for your manifest
+- [`pixi info`](./reference/cli/pixi/info.md) - show information about your workspace
+- [`pixi run`](./reference/cli/pixi/run.md) - run a task defined in your manifest or any command in the current environment
+- [`pixi shell`](./reference/cli/pixi/shell.md) - start a shell in the current environment
+- [`pixi list`](./reference/cli/pixi/list.md) - list all dependencies in the current environment
+- [`pixi tree`](./reference/cli/pixi/tree.md) - show a tree of dependencies in the current environment
+- [`pixi clean`](./reference/cli/pixi/clean.md) - remove the environment from your machine
 
-## Multiple environments
-
-We already have a quite powerful setup which is sufficient for many use cases.
-However, certain things are hard to do with the way things are set up right now.
-What if I wanted to check if my script works with multiple versions of Python?
-There cannot be multiple versions of the same package in one environment.
-Luckily, Pixi is able to manage multiple environments!
+## Managing global installations
+Pixi can manage global installations of tools and environments.
+It installs the environments in a central location, so you can use them from anywhere.
 
-Environments are composed of features, so let's create a `py312` and `py313` features each with `python` set to a different version.
-Then we will add those features to environments of the same name.
-
-```toml title="pixi.toml"
---8<-- "docs/source_files/pixi_workspaces/introduction/multi_env/pixi.toml"
-```
+- [`pixi global install`](./reference/cli/pixi/global/install.md) - install a package into it's own environment in the global space.
+- [`pixi global uninstall`](./reference/cli/pixi/global/uninstall.md) - uninstall an environment from the global space.
+- [`pixi global add`](./reference/cli/pixi/global/add.md) - add a package to an existing globally installed environment.
+- [`pixi global sync`](./reference/cli/pixi/global/sync.md) - sync the globally installed environments with the global manifest, describing all the environments you want to install.
+- [`pixi global edit`](./reference/cli/pixi/global/edit.md) - edit the global manifest.
+- [`pixi global update`](./reference/cli/pixi/global/update.md) - update the global environments
+- [`pixi global list`](./reference/cli/pixi/global/list.md) - list all the installed environments
 
-Pixi does two things behind the scenes which might not be immediately obvious.
-First, it automatically creates both a feature and environment called `default`.
-`[dependencies]` and `[tasks]` belong to that feature.
-Second, it adds the `default` feature to each environment unless you explicitly opt-out.
-That means you can read the manifest as if it were declared like this:
+More information: [Global Tools](./global_tools/introduction.md)
 
-!!! warning
+## Running one-off commands
+Pixi can run one-off commands in a specific environment.
 
-    This written out for demonstration purposes.
-    Don't spell "default" out like this in your own manifest, Pixi will do it for you behind the scenes.
+- [`pixi exec`](./reference/cli/pixi/exec.md) - run a command in a temporary environment.
+- [`pixi exec --spec`](./reference/cli/pixi/exec.md#arg---spec)   - run a command in a temporary environment, with a specific specification.
 
-```toml
-[workspace]
-channels = ["conda-forge"]
-name = "hello-world"
-platforms = ["linux-64", "osx-arm64", "win-64"]
-
-# [tasks] belong to the default feature
-[feature.default.tasks]
-start = 'python hello.py'
-
-# [dependencies] belong to the default feature
-[feature.default.dependencies]
-cowpy = "1.1.*"
-
-[feature.py312.dependencies]
-python = "3.12.*"
-
-[feature.py313.dependencies]
-python = "3.13.*"
-
-[environments]
-# Pixi automatically creates a default environment that consists only of the default feature
-default = ["default"]
-# Unless you opt-out with `no-default-feature`, every environment contains the default feature
-py312 = ["default", "py312"]
-py313 = ["default", "py313"]
-```
-
-Let's adapt the Python script so that it displays the current Python version:
-
-```py title="hello.py"
---8<-- "docs/source_files/pixi_workspaces/introduction/multi_env/hello.py"
-```
-
-The task `start` is available in both `py312` and `py313`, so we can test the script like this to test against Python 3.12:
+For example:
 
 ```bash
-pixi run --environment=py312 start
+> pixi exec python -VV
+Python 3.13.5 | packaged by conda-forge | (main, Jun 16 2025, 08:24:05) [Clang 18.1.8 ]
+> pixi exec --spec "python=3.12" python -VV
+Python 3.12.11 | packaged by conda-forge | (main, Jun  4 2025, 14:38:53) [Clang 18.1.8 ]
 ```
 
-```
- _________________________
-< Hello from Python 3.12! >
- -------------------------
-     \   ^__^
-      \  (oo)\_______
-         (__)\       )\/\
-           ||----w |
-           ||     ||
-```
+## Multiple environments
+Pixi workspaces allow you to manage multiple environments.
+An environment is build out of one or multiple features.
 
-And we can run this command to try it with Python 3.13:
+- [`pixi add --feature`](./reference/cli/pixi/add.md#arg---feature) - add a package to a feature
+- [`pixi task add --feature`](./reference/cli/pixi/task/add.md#arg---feature) - add a task to a specific feature
+- [`pixi workspace environment add`](./reference/cli/pixi/workspace/environment/add.md) - add an environment to the workspace
+- [`pixi run --environment`](./reference/cli/pixi/run.md#arg---environment) - run a command in a specific environment
+- [`pixi shell --environment`](./reference/cli/pixi/shell.md#arg---environment) - activate a specific environment
+- [`pixi list --environment`](./reference/cli/pixi/list.md#arg---environment) - list the dependencies in a specific environment
 
+More information: [Multiple environments](./workspace/multi_environment.md)
 
-```bash
-pixi run --environment=py313 start
-```
+## Tasks
+Pixi can run cross-platform tasks using it's built-in task runner.
+This can be a predefined task or any normal executable.
 
+- [`pixi run`](./reference/cli/pixi/run.md) - Run a task or command
+- [`pixi task add`](./reference/cli/pixi/task/add.md) - Add a new task to the manifest
+
+Tasks can have other tasks as dependencies.
+Here is an example of a more complex task usecase
+```toml title="pixi.toml"
+[tasks]
+build = "make build"
+# using the toml table view
+[tasks.test]
+cmd = "pytest"
+depends-on = ["build"]
 ```
- _________________________
-< Hello from Python 3.13! >
- -------------------------
-     \   ^__^
-      \  (oo)\_______
-         (__)\       )\/\
-           ||----w |
-           ||     ||
-```
+More information: [Tasks](./workspace/advanced_tasks.md)
+
+## Multi platform support
+Pixi supports multiple platforms out of the box.
+You can specify which platforms your workspace supports and Pixi will ensure that the dependencies are compatible with those platforms.
+
+- [`pixi add --platform`](./reference/cli/pixi/add.md#arg---platform) - add a package only to a specific platform
+- [`pixi workspace platform add`](./reference/cli/pixi/workspace/platform/add.md) - add a platform to the workspace that you want to support with your project
+
+More information: [Multi platform support](./workspace/multi_platform_configuration.md)
+
+## Utilities
+Pixi comes with a set of utilities to help you debug or manage your setup.
+
+- [`pixi info`](./reference/cli/pixi/info.md) - Show information about the current workspace, and the global setup.
+- [`pixi config`](./reference/cli/pixi/config.md) - Show or edit the Pixi configuration.
+- [`pixi tree`](./reference/cli/pixi/tree.md) - Show a tree of dependencies in the current environment.
+- [`pixi list`](./reference/cli/pixi/list.md) - List all dependencies in the current environment.
+- [`pixi clean`](./reference/cli/pixi/clean.md) - Remove the project environments from your machine.
+- `pixi help` - Show help for Pixi commands.
+- `pixi help <subcommand>` - Show help for a specific Pixi command.
+- [`pixi auth`](./reference/cli/pixi/auth.md) - Manage authentication for conda channels.
+- [`pixi search`](./reference/cli/pixi/search.md) - Search for packages in the configured channels.
+- [`pixi completion`](./reference/cli/pixi/completion.md) - Generate shell completion scripts for Pixi commands.
 
 
 ## Going further
diff --git a/docs/installation.md b/docs/installation.md
index c4cb0b35a5..8151a2fa73 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,3 +1,4 @@
+# Installation
 To install `pixi` you can run the following command in your terminal:
 
 === "Linux & macOS"
@@ -35,7 +36,9 @@ Now restart your terminal or shell to make the installation effective.
     You can check the installation `sh` script: [download](https://pixi.sh/install.sh) and the `ps1`: [download](https://pixi.sh/install.ps1).
     The scripts are open source and available on [GitHub](https://github.com/prefix-dev/pixi/tree/main/install).
 
-
+!!! note "Don't forget to add autocompletion!"
+    After installing Pixi, you can enable autocompletion for your shell.
+    See the [Autocompletion](#autocompletion) section below for instructions.
 ## Update
 
 Updating is as simple as installing, rerunning the installation script gets you the latest version.
@@ -213,3 +216,22 @@ Add the following to the end of `~/.elvish/rc.elv`:
 
 eval (pixi completion --shell elvish | slurp)
 ```
+
+# Uninstall
+Before un-installation you might want to delete any previous files pixi has installed.
+
+1. Remove any cached data:
+    ```shell
+    pixi clean cache
+    ```
+2. Remove the environments from your pixi projects:
+    ```shell
+    cd path/to/project && pixi clean
+    ```
+3. Remove the `pixi` and it's global environments
+    ```shell
+    rm -r ~/.pixi
+    ```
+4. Remove the pixi binary from your `PATH`:
+   - For Linux and macOS, remove `~/.pixi/bin` from your `PATH` in your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`).
+   - For Windows, remove `%UserProfile%\.pixi\bin` from your `PATH` environment variable.
diff --git a/docs/python/tutorial.md b/docs/python/tutorial.md
index 8c2c7ec4bc..5e49589b40 100644
--- a/docs/python/tutorial.md
+++ b/docs/python/tutorial.md
@@ -102,20 +102,20 @@ Which will result in the following addition to the `pyproject.toml`:
 
 ```toml
 [tool.pixi.dependencies]
-black = ">=24.10.0,<25"  # (1)!
+black = ">=25.1.0,<26"  # (1)!
 ```
 
 1. Or the latest version that is available on the [conda-forge](https://prefix.dev/channels/conda-forge/packages/black) channel.
 
 But we can also be strict about the version that should be used.
 ```shell
-pixi add black=24
+pixi add black=25
 ```
 resulting in:
 
 ```toml
 [tool.pixi.dependencies]
-black = "24.*"
+black = "25.*"
 ```
 
 Sometimes there are packages that aren't available on conda channels but are published on PyPI.
@@ -214,11 +214,15 @@ This means that you can have multiple environments with the same packages but on
     This way, Pixi automatically manages/bootstraps the Python interpreter for you, so no more `brew`, `apt` or other system install steps.
 
 ??? question "How to use the Free-threaded interpreter?"
-    If you want to use a free-threaded Python interpreter, you can add the `python-freethreading` dependency to the `[tool.pixi.dependencies]`.
+    If you want to use a free-threaded Python interpreter, you can add the `python-freethreading` dependency with:
+    ```
+    pixi add python-freethreading
+    ```
     This ensures that a free-threaded version of Python is installed in the environment.
     This might not work with other packages that are not thread-safe yet.
     You can read more about free-threaded Python [here](https://docs.python.org/3/howto/free-threading-python.html).
 
+### Multiple environments
 Pixi can also create multiple environments, this works well together with the `dependency-groups` feature in the `pyproject.toml` file.
 
 Let's add a dependency-group, which Pixi calls a `feature`, named `test`.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 05a2b37ac3..c37db8829c 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -110,6 +110,9 @@ table code {
 .md-typeset .admonition {
   font-size: 0.75rem;
 }
+.md-typeset .admonition, .md-typeset details {
+  font-size: 0.8rem;
+}
 
 
 [data-md-color-accent=prefix-light] .md-typeset .md-button:hover{
diff --git a/mkdocs.yml b/mkdocs.yml
index 3219a7b0f6..5465c2ece5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -105,8 +105,10 @@ extra:
 
 nav:
   - Home: index.md
-  - Getting Started: getting_started.md
-  - Installation: installation.md
+  - Getting Started:
+      - Installation: installation.md
+      - First project: first_project.md
+      - Basic Usage: getting_started.md
   - Workspace:
       - Environments: workspace/environment.md
       - Tasks: workspace/advanced_tasks.md