docs: README pass, add alternative editor documentation (Zed) (#4137)

I'm switching away from visual studio (because its broken) so figured
I'd document / commit the minimum to get a working environment with the
editor I chose (Zed).

Also cleaned up the main README so it's not so verbose, link out to
secondary pages, etc.

I also deleted the Arch and Fedora dockerfiles, they were broken. The
ubuntu one still works, so i left it.

docs/setup/dev/vs.md

@@ -0,0 +1,18 @@
+# Visual Studio
+
+## Known Issues
+
+- Later versions of 2022 have issues with intellisense when using clang
+- Recent versions of 2026 have issues with CMake where the project will endlessly build:
+  - https://developercommunity.visualstudio.com/t/Switching-git-branches-seemingly-causes-/11025316?viewtype=all
+
+## Steps
+
+This will create a `jak-project` folder, open the project as a CMake project via Visual Studio.
+
+![](/docs/img/windows/open-project.png)
+
+Then build the entire project as `Windows Release (clang)`. You can also press Ctrl+Shift+B as a hotkey for Build All.  We currently prefer `clang` on Windows as opposed to `msvc`, though it should work as well!
+
+![](/docs/img/windows/release-build.png)
+![](/docs/img/windows/build-all.png)

docs/setup/dev/vscode.md

@@ -0,0 +1,11 @@
+# VSCode
+
+If you either don't want to or cannot use Visual Studio for working with the C++ project, VSCode is a good alternative.
+
+The `clangd` extension is [recommended](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) and requires `clangd` to be on your `$PATH`.  If you can run `clangd` in a terminal successfully then you should be good to go.
+
+Once you generate your CMake for the first time the clangd LSP should be able to index the project and give you intellisense.
+
+## Building and Debugging
+
+TODO - Consider Contributing Documentation :)

docs/setup/dev/zed.md

@@ -0,0 +1,25 @@
+# Zed
+
+Zed comes with out of the box C++ support via `clangd`.  The project comes with a bunch of already setup task and debug configurations.  Note that many of them depend on the usage of `task` to make them cross-OS compatible (Zed at this time doesn't allow for OS-conditional logic within the task definitions).
+
+## Recommended Extensions:
+
+- NeoCMake
+
+## Building the Project
+
+We are going to build a debug version of the project because that is most useful for development.
+
+Run the `task: spawn` command (default shortcut is `Alt-Shift-T`) and run `Generate CMake: Debug`
+
+![](/docs/img/editors/zed/zed-gen-cmake.png)
+
+Then do the same thing to run `Build Project: Debug`
+
+![](/docs/img/editors/zed/zed-build-proj.png)
+
+The project is now fully built, you can now for example -- launch the REPL (`goalc`), or the game (`gk`) and attach breakpoints.
+
+![](/docs/img/editors/zed/zed-run-example.png)
+
+![](/docs/img/editors/zed/zed-debugger.png)

docs/setup/system/docker.md

@@ -0,0 +1,21 @@
+# Docker
+
+You can use docker to compile the project as well.  Note that the Dockerfiles in the project often fall out of maitenance because no one on the main development team uses them, when this is noticed, they are deleted.
+
+```sh
+docker build -f docker/Ubuntu-20.04.Dockerfile -t jak .
+```
+
+This will create an image with all required dependencies and already built.
+
+```sh
+docker run -v "$(pwd)"/build:/home/jak/jak-project/build -it jak bash
+```
+
+Note: If you change the content of the `build/` directory you'll need to rerun the `docker build` command. Alternatively you can get the build via `docker cp`.
+
+This will link your `build/` folder to the images so can validate your build or test it on an external device.
+
+Docker images can be linked into your IDE (e.g. CLion) to help with codesniffing, static analysis, run tests and continuous build.
+
+Unfortunately you'll still need task runner on your local machine to run the game or instead, manually run the game via the commands found in `Taskfile.yml`.

docs/setup/system/linux.md

@@ -0,0 +1,60 @@
+# Linux Environment Setup
+
+- [Linux Environment Setup](#linux-environment-setup)
+  - [Packages](#packages)
+    - [Ubuntu (20.04)](#ubuntu-2004)
+  - [Arch](#arch)
+  - [Fedora](#fedora)
+  - [Compiling and Building](#compiling-and-building)
+
+
+## Packages
+
+### Ubuntu (20.04)
+
+```sh
+sudo apt install gcc make cmake ninja-build build-essential g++ nasm clang-format libxrandr-dev libxinerama-dev libxcursor-dev libpulse-dev libxi-dev python libgl1-mesa-dev libssl-dev
+sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
+```
+
+## Arch
+
+```sh
+sudo pacman -S cmake libpulse base-devel nasm python libx11 libxrandr libxinerama libxcursor libxi
+yay -S go-task
+```
+
+> Note: Any later documentation that shows a `task ...` command, would instead be a `go-task ...` command.
+
+## Fedora
+
+```sh
+sudo dnf install cmake python lld clang nasm libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel pulseaudio-libs-devel mesa-libGL-devel
+sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
+```
+
+## Compiling and Building
+
+Compile:
+
+```sh
+cmake -B build && cmake --build build -j 8
+```
+
+Run tests:
+
+```sh
+./test.sh
+```
+
+Note: we have found that `clang` and `lld` are significantly faster to compile and link than `gcc`, generate faster code, and have better warning messages. To install these:
+
+```sh
+sudo apt install lld clang
+```
+
+and run `cmake` (in a fresh build directory) with:
+
+```sh
+cmake -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
+```

docs/setup/system/macos.md

@@ -0,0 +1,34 @@
+# MacOS Environment Setup
+
+Running the game requires an Apple Silicon Mac running macOS Sequoia, or an Intel Mac.  Additionally, we currently build on macOS 15 (Sequoia) at this time.
+
+Ensure that you have Xcode command line tools installed (this installs things like Apple Clang).  If you don't, you can run the following command:
+
+```bash
+xcode-select --install
+```
+
+On Apple Silicon, Rosetta 2 also must be installed:
+
+```bash
+softwareupdate --install-rosetta
+```
+
+## Building for x86_64
+
+```bash
+brew install cmake nasm ninja go-task clang-format
+cmake -B build --preset=Release-macos-x86_64-clang
+cmake --build build --parallel $((`sysctl -n hw.logicalcpu`))
+```
+
+## Building for ARM64 (experimental, unsupported)
+
+```bash
+brew install cmake ninja go-task clang-format
+cmake -B build --preset=Release-macos-arm64-clang
+cmake --build build --parallel $((`sysctl -n hw.logicalcpu`))
+```
+
+You may have to add the MacOS SDK to your `LIBRARY_PATH`:
+- `export LIBRARY_PATH="$LIBRARY_PATH:/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/lib"`

docs/setup/system/windows.md

@@ -0,0 +1,13 @@
+# Windows Environment Setup
+
+Even if you do not intend to use Visual Studio as your IDE of choice, it is the only officially supported way of downloading the various Windows SDKs to build the C++ project.
+
+Download the latest community edition from [here](https://visualstudio.microsoft.com/vs/).  At the time of writing this is Visual Studio 2022.
+
+You will require the `Desktop development with C++` workload.  This can be selected during the installation, or after via the `Visual Studio Installer` program and modifying the Visual Studio Installation.
+
+We recommend getting the rest of the project's dependencies via a package manager, and for that we use Scoop. Follow the steps on the bottom of the homepage [here](https://scoop.sh/) to get it installed.
+
+```sh
+scoop install git llvm nasm python task ninja cmake
+```