diff --git a/.flox/env/manifest.lock b/.flox/env/manifest.lock
index 5e4f4567..18c2fe9a 100644
--- a/.flox/env/manifest.lock
+++ b/.flox/env/manifest.lock
@@ -40,7 +40,7 @@
       }
     },
     "hook": {
-      "on-activate": "\n#\n# Python environment activation and installation\n#\nexport POETRY_VIRTUALENVS_PATH=\"$FLOX_ENV_CACHE/poetry/virtualenvs\"\nif [ -z \"$(poetry env info --path)\" ]; then\n  poetry env use \"$(which python)\" &> /dev/null\nfi\neval \"$(poetry env activate)\" &> /dev/null\npoetry install --quiet &> /dev/null\necho \"1. 👉 Python environment activated\"\n\n# \n# Set the version of Flox to the latest stable version\n#\nexport FLOX_VERSION=$(cat FLOX_VERSION | xargs)\necho \"2. 👉 FLOX_VERSION set to $FLOX_VERSION\"\n\n# \n# Copy and process Flox man pages\n# \nexport FLOX_SRC_ARCHIVE=\"$FLOX_ENV_CACHE/flox-v$FLOX_VERSION.tar.gz\"\nif [ ! -e \"$FLOX_SRC_ARCHIVE\" ]; then\n  curl -sL \"https://github.com/flox/flox/archive/refs/tags/v$FLOX_VERSION.tar.gz\" -o $FLOX_SRC_ARCHIVE\nfi\necho \"3. 👉 Downloaded Flox source archive\"\n\nexport FLOX_SRC_DIR=\"$FLOX_ENV_CACHE/flox-src-$FLOX_VERSION\"\nif [ ! -d \"$FLOX_SRC_DIR\" ]; then\n  mkdir -p $FLOX_SRC_DIR\n  tar -zx --strip-components=1 --file=$FLOX_SRC_ARCHIVE --directory=$FLOX_SRC_DIR;\nfi\necho \"4. 👉 Extracted Flox source archive\"\n\nexport FLOX_MAN_PAGES_DIR=\"$PWD/docs/reference/command-reference\"\nif [ -d \"$FLOX_MAN_PAGES_DIR\" ]; then\n  rm -rf \"$FLOX_MAN_PAGES_DIR/*\"\nfi\nmkdir -p $FLOX_MAN_PAGES_DIR\npushd \"$FLOX_SRC_DIR/cli/flox/doc\" > /dev/null\n  find . -maxdepth 1 -iname \"*.md\" -exec \\\n    sh -c \"\n      pandoc -t gfm \\\n        -L $FLOX_SRC_DIR/pkgs/flox-manpages/pandoc-filters/include-files.lua \\\n        --standalone \\\n        {} |\n        # remove current title\n        tail -n +6 |\n        # indent all markdown levels by one, e.g. \"#\" -> \"##\"\n        sed -e 's/^#/##/' > \\\"$FLOX_MAN_PAGES_DIR/{}\\\"\n    \" \\;\npopd > /dev/null\npushd $FLOX_MAN_PAGES_DIR > /dev/null\n  for commandPage in ./*.md; do\n    # All other man page files have names of the form\n    # 'flox*.md'\n    if [ \"$commandPage\" = \"./manifest.toml.md\" ]; then\n      continue\n    fi\n    command=$(basename $commandPage .md | sed -e \"s|-| |g\")\n    echo -e \"\\n# \\`$command\\` command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"description: Command reference for the \\`$command\\` command.\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"title: $command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n  done\n\n  manifestPage=\"manifest.toml.md\"\n  echo -e \"\\n# \\`manifest.toml\\`\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"description: Reference for the manifest.toml format.\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"title: manifest.toml\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\npopd > /dev/null\necho \"5. 👉 Copy man pages from Flox source archive\"\n"
+      "on-activate": "\n#\n# Python environment activation and installation\n#\nexport POETRY_VIRTUALENVS_PATH=\"$FLOX_ENV_CACHE/poetry/virtualenvs\"\nif [ -z \"$(poetry env info --path)\" ]; then\n  poetry env use \"$(which python)\" &> /dev/null\nfi\neval \"$(poetry env activate)\" &> /dev/null\npoetry install --quiet &> /dev/null\necho \"1. 👉 Python environment activated\"\n\n# \n# Set the version of Flox to the latest stable version\n#\nexport FLOX_VERSION=$(cat FLOX_VERSION | xargs)\necho \"2. 👉 FLOX_VERSION set to $FLOX_VERSION\"\n\n# \n# Copy and process Flox man pages\n# \nexport FLOX_SRC_ARCHIVE=\"$FLOX_ENV_CACHE/flox-v$FLOX_VERSION.tar.gz\"\nif [ ! -e \"$FLOX_SRC_ARCHIVE\" ]; then\n  curl -sL \"https://github.com/flox/flox/archive/refs/tags/v$FLOX_VERSION.tar.gz\" -o $FLOX_SRC_ARCHIVE\nfi\necho \"3. 👉 Downloaded Flox source archive\"\n\nexport FLOX_SRC_DIR=\"$FLOX_ENV_CACHE/flox-src-$FLOX_VERSION\"\nif [ ! -d \"$FLOX_SRC_DIR\" ]; then\n  mkdir -p $FLOX_SRC_DIR\n  tar -zx --strip-components=1 --file=$FLOX_SRC_ARCHIVE --directory=$FLOX_SRC_DIR;\nfi\necho \"4. 👉 Extracted Flox source archive\"\n\nexport FLOX_MAN_PAGES_DIR=\"$PWD/docs/man\"\nif [ -d \"$FLOX_MAN_PAGES_DIR\" ]; then\n  rm -rf \"$FLOX_MAN_PAGES_DIR/*\"\nfi\nmkdir -p $FLOX_MAN_PAGES_DIR\npushd \"$FLOX_SRC_DIR/cli/flox/doc\" > /dev/null\n  find . -maxdepth 1 -iname \"*.md\" -exec \\\n    sh -c \"\n      pandoc -t gfm \\\n        -L $FLOX_SRC_DIR/pkgs/flox-manpages/pandoc-filters/include-files.lua \\\n        --standalone \\\n        {} |\n        # remove current title\n        tail -n +6 |\n        # indent all markdown levels by one, e.g. \"#\" -> \"##\"\n        sed -e 's/^#/##/' > \\\"$FLOX_MAN_PAGES_DIR/{}\\\"\n    \" \\;\npopd > /dev/null\npushd $FLOX_MAN_PAGES_DIR > /dev/null\n  for commandPage in ./*.md; do\n    # All other man page files have names of the form\n    # 'flox*.md'\n    if [ \"$commandPage\" = \"./manifest.toml.md\" ]; then\n      continue\n    fi\n    command=$(basename $commandPage .md | sed -e \"s|-| |g\")\n    echo -e \"\\n# \\`$command\\` command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"description: Command reference for the \\`$command\\` command.\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"title: $command\\n$(cat $commandPage)\" > $commandPage\n    echo -e \"---\\n$(cat $commandPage)\" > $commandPage\n  done\n\n  manifestPage=\"manifest.toml.md\"\n  echo -e \"\\n# \\`manifest.toml\\`\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"description: Reference for the manifest.toml format.\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"title: manifest.toml\\n$(cat $manifestPage)\" > $manifestPage\n  echo -e \"---\\n$(cat $manifestPage)\" > $manifestPage\npopd > /dev/null\necho \"5. 👉 Copy man pages from Flox source archive\"\n"
     },
     "profile": {
       "common": "echo \"\"\necho \"     ╔═══════════════════════════════════╗\"\necho \"     ║                                   ║\"\necho \"     ║  To build a production docs run:  ║\"\necho \"     ║  > mkdocs build                   ║\"\necho \"     ║                                   ║\"\necho \"     ║  To write docs locally run:       ║\"\necho \"     ║  > mkdocs serve                   ║\"\necho \"     ║                                   ║\"\necho \"     ╚═══════════════════════════════════╝\"\necho \"\"\n",
diff --git a/.flox/env/manifest.toml b/.flox/env/manifest.toml
index 9a7fc78b..df77ae2b 100644
--- a/.flox/env/manifest.toml
+++ b/.flox/env/manifest.toml
@@ -52,7 +52,7 @@ if [ ! -d "$FLOX_SRC_DIR" ]; then
 fi
 echo "4. 👉 Extracted Flox source archive"
 
-export FLOX_MAN_PAGES_DIR="$PWD/docs/reference/command-reference"
+export FLOX_MAN_PAGES_DIR="$PWD/docs/man"
 if [ -d "$FLOX_MAN_PAGES_DIR" ]; then
   rm -rf "$FLOX_MAN_PAGES_DIR/*"
 fi
diff --git a/.gitignore b/.gitignore
index 6ea01ce7..db1b430b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,7 @@
 .direnv/
 site/
 include/
-docs/reference/command-reference
+docs/man
 result
 result-*
 bin/
diff --git a/docs/concepts/activation.md b/docs/concepts/activation.md
index c0b26f03..e26d693d 100644
--- a/docs/concepts/activation.md
+++ b/docs/concepts/activation.md
@@ -310,7 +310,7 @@ attach to this new version of the environment.
 
 ## Development vs. runtime mode
 
-See the [`options.activate.mode`](../reference/command-reference/manifest.toml.md#options) option in the manifest.
+See the [`options.activate.mode`](../man/manifest.toml.md#options) option in the manifest.
 
 ## Conclusion
 
@@ -329,6 +329,6 @@ that prepare your environment just how you like them.
 
 [environment-concept]: ./services.md
 [bash-func-export]: https://www.gnu.org/software/bash/manual/html_node/Bourne-Shell-Builtins.html#index-export
-[vars-section]: ../reference/command-reference/manifest.toml.md#vars
-[hook-section]: ../reference/command-reference/manifest.toml.md#hook
-[profile-section]: ../reference/command-reference/manifest.toml.md#profile
+[vars-section]: ../man/manifest.toml.md#vars
+[hook-section]: ../man/manifest.toml.md#hook
+[profile-section]: ../man/manifest.toml.md#profile
diff --git a/docs/concepts/builds.md b/docs/concepts/builds.md
index 5af89062..7207d351 100644
--- a/docs/concepts/builds.md
+++ b/docs/concepts/builds.md
@@ -42,5 +42,5 @@ One way to accomplish this is to run your builds in [CI][flox-ci-cd].
 
 [manifest-builds-concept]: ./manifest-builds.md
 [nix-expression-builds-concept]: ./nix-expression-builds.md
-[flox-build]: ../reference/command-reference/flox-build.md
+[flox-build]: ../man/flox-build.md
 [flox-ci-cd]: ../tutorials/ci-cd.md
diff --git a/docs/concepts/environments.md b/docs/concepts/environments.md
index e9e99acc..8ee2be82 100644
--- a/docs/concepts/environments.md
+++ b/docs/concepts/environments.md
@@ -110,21 +110,21 @@ version. Flox manages this file for you.
 }
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
+[flox_init]: ../man/flox-init.md
+[flox_show]: ../man/flox-show.md
+[flox_edit]: ../man/flox-edit.md
+[flox_install]: ../man/flox-install.md
+[flox_search]: ../man/flox-search.md
+[flox_edit]: ../man/flox-edit.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
 [sharing_guide]: ../tutorials/sharing-environments.md
 [create_guide]: ../tutorials/creating-environments.md
 [customizing_environments_guide]: ../tutorials/customizing-environments.md
 [generation_concept]: ./generations.md
 [floxhub_concept]: ./floxhub.md
 [discourse]: https://discourse.flox.dev/
-[manifest]: ../reference/command-reference/manifest.toml.md
+[manifest]: ../man/manifest.toml.md
 [nix-expression-builds-concept]: ./nix-expression-builds.md
 [toml_spec]: https://toml.io/en/v1.0.0
diff --git a/docs/concepts/flox-vs-containers.md b/docs/concepts/flox-vs-containers.md
index 8d0379b1..dd95c7d5 100644
--- a/docs/concepts/flox-vs-containers.md
+++ b/docs/concepts/flox-vs-containers.md
@@ -439,13 +439,13 @@ you need to build a container so that it can be deployed.
 
 ---
 
-[init]: ../reference/command-reference/flox-init.md
-[edit]: ../reference/command-reference/flox-edit.md
-[install]: ../reference/command-reference/flox-install.md
-[push]: ../reference/command-reference/flox-push.md
-[containerize]: ../reference/command-reference/flox-containerize.md
-[activate]: ../reference/command-reference/flox-activate.md
-[services-start]: ../reference/command-reference/flox-services-start.md
+[init]: ../man/flox-init.md
+[edit]: ../man/flox-edit.md
+[install]: ../man/flox-install.md
+[push]: ../man/flox-push.md
+[containerize]: ../man/flox-containerize.md
+[activate]: ../man/flox-activate.md
+[services-start]: ../man/flox-services-start.md
 [services]: ../concepts/services.md
 [manifest]: ../concepts/environments.md#manifesttoml
 [early]: https://flox.dev/early/
diff --git a/docs/concepts/floxhub.md b/docs/concepts/floxhub.md
index 948a3f8a..bfbd7162 100644
--- a/docs/concepts/floxhub.md
+++ b/docs/concepts/floxhub.md
@@ -97,13 +97,13 @@ flox pull example-owner/example-env
 Run the [`flox auth logout`][flox_auth] command.
 
 [flox_website]: https://flox.dev
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_auth]: ../reference/command-reference/flox-auth.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_uninstall]: ../reference/command-reference/flox-uninstall.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
+[flox_auth]: ../man/flox-auth.md
+[flox_edit]: ../man/flox-edit.md
+[flox_install]: ../man/flox-install.md
+[flox_uninstall]: ../man/flox-uninstall.md
 [generation_concept]: ../concepts/generations.md
 [manifest_concept]: ../concepts/environments.md#manifesttoml
 [environments_concept]: ../concepts/environments.md
diff --git a/docs/concepts/generations.md b/docs/concepts/generations.md
index 6209e147..64b763c8 100644
--- a/docs/concepts/generations.md
+++ b/docs/concepts/generations.md
@@ -79,9 +79,9 @@ This allows this environment to advance to newer generations explicitly on the
 next [`flox pull`][flox_pull].
 
 [floxhub_concept]: .//floxhub.md
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
+[flox_push]: ../man/flox-push.md
+[flox_install]: ../man/flox-install.md
+[flox_edit]: ../man/flox-edit.md
+[flox_pull]: ../man/flox-pull.md
 [sharing_guide]: ../tutorials/sharing-environments.md
 [environment_guide]: ../tutorials/creating-environments.md
diff --git a/docs/concepts/manifest-builds.md b/docs/concepts/manifest-builds.md
index ff57f98b..3d7d1dab 100644
--- a/docs/concepts/manifest-builds.md
+++ b/docs/concepts/manifest-builds.md
@@ -190,11 +190,11 @@ Each language guide in the Languages section of the Cookbook contains an example
 For example, [this section][go-example] contains an example build for the Go language.
 
 [builds-concept]: ./builds.md
-[manifest-reference]: ../reference/command-reference/manifest.toml.md#build
+[manifest-reference]: ../man/manifest.toml.md#build
 [services-concept]: ./services.md
 [publish-concept]: ./publishing.md
 [fhs-docs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
-[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors
+[pkg-groups]: ../man/manifest.toml.md#package-descriptors
 [grpc]: https://grpc.io/
 [organizations-concept]: ./organizations.md
-[go-example]: ../cookbook/languages/go.md#build-with-flox
+[go-example]: ../languages/go.md#build-with-flox
diff --git a/docs/concepts/nix-expression-builds.md b/docs/concepts/nix-expression-builds.md
index 80820f10..b8082d6c 100644
--- a/docs/concepts/nix-expression-builds.md
+++ b/docs/concepts/nix-expression-builds.md
@@ -242,4 +242,4 @@ error: hash mismatch in fixed-output derivation '/nix/store/srm7s6pyckifs52ikyfa
 
 [builds-concept]: ./builds.md
 [manifest-builds-concept]: ./manifest-builds.md
-[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors
+[pkg-groups]: ../man/manifest.toml.md#package-descriptors
diff --git a/docs/concepts/packages-and-catalog.md b/docs/concepts/packages-and-catalog.md
index 8640c59a..53de4534 100644
--- a/docs/concepts/packages-and-catalog.md
+++ b/docs/concepts/packages-and-catalog.md
@@ -38,10 +38,10 @@ Source by the Open Source Initiative (OSI).
 * **broken**: indicates if the package is marked as broken in
 [nixpkgs][nixpkgs].
 
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_update]: ../reference/command-reference/flox-update.md
+[flox_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_install]: ../man/flox-install.md
+[flox_update]: ../man/flox-update.md
 [manifest_concept]: ./environments.md#manifesttoml
 [nixpkgs]: https://github.com/NixOS/nixpkgs
 [builds]: ./builds.md
diff --git a/docs/concepts/publishing.md b/docs/concepts/publishing.md
index f2de7a9c..145abb1f 100644
--- a/docs/concepts/publishing.md
+++ b/docs/concepts/publishing.md
@@ -83,9 +83,9 @@ For anyone in the organization, published packages become available in
 
 [builds-concept]: ./builds.md
 [catalog-concept]: ./packages-and-catalog.md
-[flox-build]: ../reference/command-reference/flox-build.md
-[flox-publish]: ../reference/command-reference/flox-publish.md
-[flox-search]: ../reference/command-reference/flox-search.md
-[flox-show]: ../reference/command-reference/flox-show.md
-[flox-install]: ../reference/command-reference/flox-install.md
+[flox-build]: ../man/flox-build.md
+[flox-publish]: ../man/flox-publish.md
+[flox-search]: ../man/flox-search.md
+[flox-show]: ../man/flox-show.md
+[flox-install]: ../man/flox-install.md
 [organizations-concept]: ./organizations.md
diff --git a/docs/concepts/services.md b/docs/concepts/services.md
index f627063c..431ce03f 100644
--- a/docs/concepts/services.md
+++ b/docs/concepts/services.md
@@ -28,7 +28,7 @@ Services have a very simple schema consisting of a `command` to run to start
 the service,
 any `vars` you want set specifically for the service,
 and whether the service spawns a background process.
-See [`manifest-toml(1)`](../reference/command-reference/manifest.toml.md) for
+See [`manifest-toml(1)`](../man/manifest.toml.md) for
 more details on the exact format of the `[services]` section of the manfiest.
 
 An example service definition is shown below:
diff --git a/docs/flox-5-minutes.md b/docs/flox-5-minutes.md
index 6e0fe7ab..643e9b72 100644
--- a/docs/flox-5-minutes.md
+++ b/docs/flox-5-minutes.md
@@ -252,23 +252,23 @@ There are _so_ many things we didn't have time to cover, so here's some addition
 [install_flox]: ./install-flox/install.md
 [create_guide]: ./tutorials/creating-environments.md
 [sharing]: ./tutorials/sharing-environments.md
-[init]: ./reference/command-reference/flox-init.md
-[search]: ./reference/command-reference/flox-search.md
-[show]: ./reference/command-reference/flox-show.md
+[init]: ./man/flox-init.md
+[search]: ./man/flox-search.md
+[show]: ./man/flox-show.md
 [catalog]: ./concepts/packages-and-catalog.md
-[install]: ./reference/command-reference/flox-install.md
-[activate]: ./reference/command-reference/flox-activate.md
-[edit]: ./reference/command-reference/flox-edit.md
-[push]: ./reference/command-reference/flox-push.md
-[list]: ./reference/command-reference/flox-list.md
-[manifest]: ./reference/command-reference/manifest.toml.md
+[install]: ./man/flox-install.md
+[activate]: ./man/flox-activate.md
+[edit]: ./man/flox-edit.md
+[push]: ./man/flox-push.md
+[list]: ./man/flox-list.md
+[manifest]: ./man/manifest.toml.md
 [multi-arch]: ./tutorials/multi-arch-environments.md
 [services]: ./concepts/services.md
 [bun]: https://bun.sh/
 [zig]: https://ziglang.org/
 [floxhub]: https://hub.flox.dev
 [sleep-issue]: https://github.com/flox/flox/pull/1931
-[install-section]: ./reference/command-reference/manifest.toml.md#install
+[install-section]: ./man/manifest.toml.md#install
 [activation-tutorial]: ./tutorials/customizing-environments.md
 [ci]: ./tutorials/ci-cd.md
 [composition]: ./tutorials/composition.md
diff --git a/docs/index.md b/docs/index.md
index a129558f..5e5fa8a9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -108,7 +108,7 @@ If you're already using Homebrew, you can easily [migrate or use Homebrew and Fl
 Flox lets you define what an environment _is_ in a way that can be reused across local dev, CI, and production.
 Leverage [pre-built integrations](https://flox.dev/docs/tutorials/ci-cd/?h=ci) for GitHub Actions, CircleCI, and GitLab to pull and activate the same environments locally, in CI and in production.
 
-Or use Flox [containerize](https://flox.dev/docs/reference/command-reference/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere.
+Or use Flox [containerize](https://flox.dev/docs/man/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere.
 From bare metal to VMs, from Docker Swarm to Kubernetes to AWS Lambda—the runtime context might change, but Flox environments run and behave the same everywhere.
 
 Need an example? See how [the Flox Docs team uses Flox in CI](https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/) to build, test and deploy this docs site.
@@ -131,20 +131,20 @@ The Flox product and engineering teams love to hear directly from users. Your qu
 [flox_5_minutes]: ./flox-5-minutes.md
 [create_guide]: ./tutorials/creating-environments.md
 [share_guide]: ./tutorials/sharing-environments.md
-[init]: ./reference/command-reference/flox-init.md
-[search]: ./reference/command-reference/flox-search.md
-[show]: ./reference/command-reference/flox-show.md
+[init]: ./man/flox-init.md
+[search]: ./man/flox-search.md
+[show]: ./man/flox-show.md
 [catalog]: ./concepts/packages-and-catalog.md
-[install]: ./reference/command-reference/flox-install.md
-[activate]: ./reference/command-reference/flox-activate.md
-[edit]: ./reference/command-reference/flox-edit.md
-[push]: ./reference/command-reference/flox-push.md
-[pull]: ./reference/command-reference/flox-pull.md
-[delete]: ./reference/command-reference/flox-delete.md
-[list]: ./reference/command-reference/flox-list.md
-[manifest]: ./reference/command-reference/manifest.toml.md
-[rust-cookbook]: ./cookbook/languages/rust.md
+[install]: ./man/flox-install.md
+[activate]: ./man/flox-activate.md
+[edit]: ./man/flox-edit.md
+[push]: ./man/flox-push.md
+[pull]: ./man/flox-pull.md
+[delete]: ./man/flox-delete.md
+[list]: ./man/flox-list.md
+[manifest]: ./man/manifest.toml.md
+[rust-cookbook]: ./languages/rust.md
 [multi-arch]: ./tutorials/multi-arch-environments.md
-[config]: ./reference/command-reference/flox-config.md
+[config]: ./man/flox-config.md
 [services]: ./concepts/services.md
 [floxhub_packages]: https://hub.flox.dev/packages
diff --git a/docs/cookbook/languages/c.md b/docs/languages/c.md
similarity index 96%
rename from docs/cookbook/languages/c.md
rename to docs/languages/c.md
index 47c8946b..d6f4b372 100644
--- a/docs/cookbook/languages/c.md
+++ b/docs/languages/c.md
@@ -55,4 +55,4 @@ clangStdenv.mkDerivation {
 }
 ```
 
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/cookbook/languages/go.md b/docs/languages/go.md
similarity index 93%
rename from docs/cookbook/languages/go.md
rename to docs/languages/go.md
index a6ce8dd1..cb93b262 100644
--- a/docs/cookbook/languages/go.md
+++ b/docs/languages/go.md
@@ -107,6 +107,6 @@ buildGoModule {
 }
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
-[nix-expression-hashes]: ../../concepts/nix-expression-builds.md#generating-hashes
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
+[nix-expression-hashes]: ../concepts/nix-expression-builds.md#generating-hashes
diff --git a/docs/cookbook/languages/jvm.md b/docs/languages/jvm.md
similarity index 97%
rename from docs/cookbook/languages/jvm.md
rename to docs/languages/jvm.md
index ea74b6e1..159cbbd5 100644
--- a/docs/cookbook/languages/jvm.md
+++ b/docs/languages/jvm.md
@@ -44,4 +44,4 @@ Note that `pwd` will return the location from which the built artifact is run, n
 
 [gradle]: https://gradle.org/
 [shadow]: https://gradleup.com/shadow/
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/cookbook/languages/nodejs.md b/docs/languages/nodejs.md
similarity index 95%
rename from docs/cookbook/languages/nodejs.md
rename to docs/languages/nodejs.md
index 54938175..53ba5ce7 100644
--- a/docs/cookbook/languages/nodejs.md
+++ b/docs/languages/nodejs.md
@@ -97,5 +97,5 @@ buildNpmPackage (final: {
 });
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/cookbook/languages/python.md b/docs/languages/python.md
similarity index 99%
rename from docs/cookbook/languages/python.md
rename to docs/languages/python.md
index 84697324..58cddb87 100644
--- a/docs/cookbook/languages/python.md
+++ b/docs/languages/python.md
@@ -355,4 +355,4 @@ runtime-packages = [
 ]
 ```
 
-[build-concept]: ../../concepts/builds.md
+[build-concept]: ../concepts/builds.md
diff --git a/docs/cookbook/languages/ruby.md b/docs/languages/ruby.md
similarity index 95%
rename from docs/cookbook/languages/ruby.md
rename to docs/languages/ruby.md
index 6b10afde..9df5e676 100644
--- a/docs/cookbook/languages/ruby.md
+++ b/docs/languages/ruby.md
@@ -82,5 +82,5 @@ command = """
 sandbox = "pure"
 ```
 
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/cookbook/languages/rust.md b/docs/languages/rust.md
similarity index 98%
rename from docs/cookbook/languages/rust.md
rename to docs/languages/rust.md
index bbc21eb9..a0bd353f 100644
--- a/docs/cookbook/languages/rust.md
+++ b/docs/languages/rust.md
@@ -289,5 +289,5 @@ rustPlatform.buildRustPackage {
 [custom-toolchains]: https://github.com/zmitchell/rust-toolchains
 [esp32]: https://www.espressif.com/en/products/socs/esp32
 [risc-v]: https://en.wikipedia.org/wiki/RISC-V
-[build-concept]: ../../concepts/builds.md
-[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds
+[build-concept]: ../concepts/builds.md
+[pure-builds-section]: ../concepts/manifest-builds.md#pure-builds
diff --git a/docs/tutorials/build-and-publish.md b/docs/tutorials/build-and-publish.md
index 606d6556..2daa9c5b 100644
--- a/docs/tutorials/build-and-publish.md
+++ b/docs/tutorials/build-and-publish.md
@@ -256,15 +256,15 @@ The story doesn't end here though.
 In this guide we've shown you how to build and distribute programs, but you can also use it to distribute configuration files (or any other file).
 See the [builds][extra-builds] concept page for examples of what else you can build and publish with Flox.
 
-[flox-manifest-build-section]: ../reference/command-reference/manifest.toml.md#build
+[flox-manifest-build-section]: ../man/manifest.toml.md#build
 [build-concept]: ../concepts/builds.md
 [fhs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
-[flox-install]: ../reference/command-reference/flox-install.md
-[flox-show]: ../reference/command-reference/flox-show.md
-[flox-search]: ../reference/command-reference/flox-search.md
-[flox-edit]: ../reference/command-reference/flox-edit.md
-[flox-build]: ../reference/command-reference/flox-build.md
-[flox-publish]: ../reference/command-reference/flox-publish.md
+[flox-install]: ../man/flox-install.md
+[flox-show]: ../man/flox-show.md
+[flox-search]: ../man/flox-search.md
+[flox-edit]: ../man/flox-edit.md
+[flox-build]: ../man/flox-build.md
+[flox-publish]: ../man/flox-publish.md
 [extra-builds]: ../concepts/manifest-builds.md#example-configuration-files
 [publish-concept]: ../concepts/publishing.md
 [organizations-concept]: ../concepts/organizations.md
diff --git a/docs/tutorials/ci-cd.md b/docs/tutorials/ci-cd.md
index b40200c3..788c17f8 100644
--- a/docs/tutorials/ci-cd.md
+++ b/docs/tutorials/ci-cd.md
@@ -121,4 +121,4 @@ Here are some suggestions for things you can do with your Flox environment in CI
 [sharing_guide]: ./sharing-environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [customizing_guide]: ./customizing-environments.md
-[containerize]: ../reference/command-reference/flox-containerize.md
+[containerize]: ../man/flox-containerize.md
diff --git a/docs/tutorials/composition.md b/docs/tutorials/composition.md
index f6280642..2da10762 100644
--- a/docs/tutorials/composition.md
+++ b/docs/tutorials/composition.md
@@ -297,10 +297,10 @@ This means you can spend less time getting started, and more time developing you
 Similarly, since you're treating environments like dependencies, if you make an improvement to a template environment while working on one project, the improvement will become available to all of your other projects that use that environment as soon as they run `flox include upgrade`.
 
 [poetry]: https://python-poetry.org/
-[flox-init]: ../reference/command-reference/flox-init.md
-[flox-pull]: ../reference/command-reference/flox-pull.md
-[flox-install]: ../reference/command-reference/flox-install.md
-[flox-edit]: ../reference/command-reference/flox-edit.md
-[flox-list]: ../reference/command-reference/flox-list.md
+[flox-init]: ../man/flox-init.md
+[flox-pull]: ../man/flox-pull.md
+[flox-install]: ../man/flox-install.md
+[flox-edit]: ../man/flox-edit.md
+[flox-list]: ../man/flox-list.md
 [floxhub]: ../concepts/floxhub.md
 [hypothesis]: https://hypothesis.readthedocs.io/en/latest/
diff --git a/docs/tutorials/creating-environments.md b/docs/tutorials/creating-environments.md
index a67a2e65..bb4db40f 100644
--- a/docs/tutorials/creating-environments.md
+++ b/docs/tutorials/creating-environments.md
@@ -228,13 +228,13 @@ flox [example-project] $ exit
 $
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_install]: ../reference/command-reference/flox-install.md
+[flox_init]: ../man/flox-init.md
+[flox_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_install]: ../man/flox-install.md
 [discourse]: https://discourse.floxdev.com/
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
+[flox_activate]: ../man/flox-activate.md
+[flox_edit]: ../man/flox-edit.md
 [sharing_guide]: ./sharing-environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [manifest_concept]: ../concepts/environments.md#manifesttoml
diff --git a/docs/tutorials/customizing-environments.md b/docs/tutorials/customizing-environments.md
index d1761382..36d7ea7d 100644
--- a/docs/tutorials/customizing-environments.md
+++ b/docs/tutorials/customizing-environments.md
@@ -174,10 +174,10 @@ mycli
 - :simple-readme:{ .flox-purple .flox-heart } [Multiple architecture environments][multi-arch-guide]
 
 [environment_concept]: ../concepts/environments.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
+[flox_activate]: ../man/flox-activate.md
 [multi-arch-guide]: ./multi-arch-environments.md
-[rust_guide]: ../cookbook/languages/rust.md
-[flox_init]: ../reference/command-reference/flox-init.md
+[rust_guide]: ../languages/rust.md
+[flox_init]: ../man/flox-init.md
 [activation_concept]: ../concepts/activation.md
 [fish_shell]: https://fishshell.com/
-[flox_install]: ../reference/command-reference/flox-install.md
+[flox_install]: ../man/flox-install.md
diff --git a/docs/tutorials/default-environment.md b/docs/tutorials/default-environment.md
index 3e8285d0..de374574 100644
--- a/docs/tutorials/default-environment.md
+++ b/docs/tutorials/default-environment.md
@@ -247,6 +247,6 @@ Flox has you covered.
 Even better, if you want both a package manager _and_ developer environments,
 with Flox you only need to learn one tool.
 
-[init]: ../reference/command-reference/flox-init.md
-[push]: ../reference/command-reference/flox-push.md
-[pull]: ../reference/command-reference/flox-pull.md
+[init]: ../man/flox-init.md
+[push]: ../man/flox-push.md
+[pull]: ../man/flox-pull.md
diff --git a/docs/tutorials/layering-multiple-environments.md b/docs/tutorials/layering-multiple-environments.md
index 25d7377f..4b75a8f8 100644
--- a/docs/tutorials/layering-multiple-environments.md
+++ b/docs/tutorials/layering-multiple-environments.md
@@ -127,10 +127,10 @@ Inactive environments:
 - :simple-readme:{ .flox-purple .flox-heart } [Designing multiple architecture environments][multi_arch_guide]
 
 [default-env]: ./default-environment.md
-[flox_init]: ../reference/command-reference/flox-init.md
-[flox_install]: ../reference/command-reference/flox-install.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
-[flox_list]: ../reference/command-reference/flox-list.md
+[flox_init]: ../man/flox-init.md
+[flox_install]: ../man/flox-install.md
+[flox_activate]: ../man/flox-activate.md
+[flox_list]: ../man/flox-list.md
 [sharing_guide]: ./sharing-environments.md
 [customizing_guide]: ./customizing-environments.md
 [multi_arch_guide]: ./multi-arch-environments.md
diff --git a/docs/tutorials/migrations/homebrew.md b/docs/tutorials/migrations/homebrew.md
index eb772a58..77311e27 100644
--- a/docs/tutorials/migrations/homebrew.md
+++ b/docs/tutorials/migrations/homebrew.md
@@ -202,10 +202,10 @@ We recommend that the Flox default environment activation lines appear lowest in
 [default_tutorial_setup]: ../default-environment.md#initial-setup
 [creating_tutorial]: ../creating-environments.md
 [install_flox]: ../../install-flox/install.md
-[search]: ../../reference/command-reference/flox-search.md
-[envs]: ../../reference/command-reference/flox-envs.md
-[list]: ../../reference/command-reference/flox-list.md
+[search]: ../../man/flox-search.md
+[envs]: ../../man/flox-envs.md
+[list]: ../../man/flox-list.md
 [catalog]: ../../concepts/packages-and-catalog.md
-[install]: ../../reference/command-reference/flox-install.md
-[uninstall]: ../../reference/command-reference/flox-uninstall.md
-[activate]: ../../reference/command-reference/flox-activate.md
+[install]: ../../man/flox-install.md
+[uninstall]: ../../man/flox-uninstall.md
+[activate]: ../../man/flox-activate.md
diff --git a/docs/tutorials/migrations/nvm.md b/docs/tutorials/migrations/nvm.md
index f71b7a34..90c54514 100644
--- a/docs/tutorials/migrations/nvm.md
+++ b/docs/tutorials/migrations/nvm.md
@@ -189,5 +189,5 @@ Now that you're managing your project's Node.js version using Flox, you can `git
 
 [environment_concept]: ../../concepts/environments.md
 [install_flox]: ../../install-flox/install.md
-[manifest]: ../../reference/command-reference/manifest.toml.md
+[manifest]: ../../man/manifest.toml.md
 [services]: ../../concepts/services.md
diff --git a/docs/tutorials/multi-arch-environments.md b/docs/tutorials/multi-arch-environments.md
index 41c92525..826e240e 100644
--- a/docs/tutorials/multi-arch-environments.md
+++ b/docs/tutorials/multi-arch-environments.md
@@ -138,8 +138,8 @@ get the `systemd` package.
 
 [environment_concept]: ../concepts/environments.md
 [sharing_guide]: ./sharing-environments.md
-[flox_search]: ../reference/command-reference/flox-search.md
-[flox_show]: ../reference/command-reference/flox-show.md
-[flox_edit]: ../reference/command-reference/flox-edit.md
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
+[flox_search]: ../man/flox-search.md
+[flox_show]: ../man/flox-show.md
+[flox_edit]: ../man/flox-edit.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
diff --git a/docs/tutorials/sharing-environments.md b/docs/tutorials/sharing-environments.md
index b5c0a337..c4afa532 100644
--- a/docs/tutorials/sharing-environments.md
+++ b/docs/tutorials/sharing-environments.md
@@ -54,7 +54,7 @@ git clone ..example-project;
 flox activate
 ```
 
-[flox_init]: ../reference/command-reference/flox-init.md
+[flox_init]: ../man/flox-init.md
 [discourse]: https://discourse.flox.dev/
 [manifest_concept]: ../concepts/environments.md#manifesttoml
 
@@ -128,9 +128,9 @@ $ flox push
 !!! note "Note"
     Right now, only environment owners can push edits to their environments.
 
-[flox_push]: ../reference/command-reference/flox-push.md
-[flox_pull]: ../reference/command-reference/flox-pull.md
-[flox_activate]: ../reference/command-reference/flox-activate.md
+[flox_push]: ../man/flox-push.md
+[flox_pull]: ../man/flox-pull.md
+[flox_activate]: ../man/flox-activate.md
 [floxhub_concept]: ../concepts/floxhub.md
 
 ### Pulling a remote environment without connecting to FloxHub
@@ -228,4 +228,4 @@ telnet (GNU inetutils) 2.5
 [environment_concept]: ../concepts/environments.md
 [layering_guide]: ./layering-multiple-environments.md
 [customizing_guide]: ./customizing-environments.md
-[flox_containerize]: ../reference/command-reference/flox-containerize.md
+[flox_containerize]: ../man/flox-containerize.md
diff --git a/mkdocs.yml b/mkdocs.yml
index 26637d56..1d51865e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -65,13 +65,11 @@ nav:
     - Nix expression builds: concepts/nix-expression-builds.md
     - Publishing: concepts/publishing.md
     - Flox vs. container workflows: concepts/flox-vs-containers.md
-  - Cookbook:
-    - Languages:
-      - ... | flat | cookbook/languages/*
-  - Reference:
-    - Flox manual:
-      - reference/command-reference/flox.md
-      - ... | flat | reference/command-reference/*
+  - Languages:
+    - ... | flat | languages/*
+  - Manual:
+    - man/flox.md
+    - ... | flat | man/*
 
 strict: true
 validation:
@@ -310,3 +308,43 @@ plugins:
         redirect_maps:
             'concepts/manifest.md': 'concepts/environments.md#manifesttoml'
             'install-flox.md': 'install-flox/install.md'
+            'reference/command-reference/flox-activate.md': 'man/flox-activate.md'
+            'reference/command-reference/flox-auth.md': 'man/flox-auth.md'
+            'reference/command-reference/flox-build-clean.md': 'man/flox-build-clean.md'
+            'reference/command-reference/flox-build-import-nixpkgs.md': 'man/flox-build-import-nixpkgs.md'
+            'reference/command-reference/flox-build.md': 'man/flox-build.md'
+            'reference/command-reference/flox-config.md': 'man/flox-config.md'
+            'reference/command-reference/flox-containerize.md': 'man/flox-containerize.md'
+            'reference/command-reference/flox-delete.md': 'man/flox-delete.md'
+            'reference/command-reference/flox-edit.md': 'man/flox-edit.md'
+            'reference/command-reference/flox-envs.md': 'man/flox-envs.md'
+            'reference/command-reference/flox-gc.md': 'man/flox-gc.md'
+            'reference/command-reference/flox-generations-history.md': 'man/flox-generations-history.md'
+            'reference/command-reference/flox-generations-list.md': 'man/flox-generations-list.md'
+            'reference/command-reference/flox-generations-rollback.md': 'man/flox-generations-rollback.md'
+            'reference/command-reference/flox-generations-switch.md': 'man/flox-generations-switch.md'
+            'reference/command-reference/flox-include-upgrade.md': 'man/flox-include-upgrade.md'
+            'reference/command-reference/flox-init.md': 'man/flox-init.md'
+            'reference/command-reference/flox-install.md': 'man/flox-install.md'
+            'reference/command-reference/flox-list.md': 'man/flox-list.md'
+            'reference/command-reference/flox-publish.md': 'man/flox-publish.md'
+            'reference/command-reference/flox-pull.md': 'man/flox-pull.md'
+            'reference/command-reference/flox-push.md': 'man/flox-push.md'
+            'reference/command-reference/flox-search.md': 'man/flox-search.md'
+            'reference/command-reference/flox-services-logs.md': 'man/flox-services-logs.md'
+            'reference/command-reference/flox-services-restart.md': 'man/flox-services-restart.md'
+            'reference/command-reference/flox-services-start.md': 'man/flox-services-start.md'
+            'reference/command-reference/flox-services-status.md': 'man/flox-services-status.md'
+            'reference/command-reference/flox-services-stop.md': 'man/flox-services-stop.md'
+            'reference/command-reference/flox-show.md': 'man/flox-show.md'
+            'reference/command-reference/flox-uninstall.md': 'man/flox-uninstall.md'
+            'reference/command-reference/flox-upgrade.md': 'man/flox-upgrade.md'
+            'reference/command-reference/flox.md': 'man/flox.md'
+            'reference/command-reference/manifest.toml.md': 'man/manifest.toml.md'
+            'cookbook/languages/c.md': 'languages/c.md'
+            'cookbook/languages/go.md': 'languages/go.md'
+            'cookbook/languages/jvm.md': 'languages/jvm.md'
+            'cookbook/languages/nodejs.md': 'languages/nodejs.md'
+            'cookbook/languages/python.md': 'languages/python.md'
+            'cookbook/languages/ruby.md': 'languages/ruby.md'
+            'cookbook/languages/rust.md': 'languages/rust.md'