add install options pages

docs/getting-started/docker.mdx

@@ -161,6 +161,6 @@ image that already has the debugger in it.
 
 ## Next steps
 
-- [More install options](./install-options.md) — prebuilt binaries, package
-  managers, and building from source
+- [More install options](./install-options/index.md) — PIE, prebuilt binaries,
+  and building from source
 - [Configuration](./configuration.md) — the settings you can change

docs/getting-started/install-options/binaries.mdx

@@ -0,0 +1,106 @@
+---
+title: Prebuilt binaries
+---
+
+import ConsoleSample from '@site/src/components/ConsoleSample';
+
+Every release ships ready-built binaries on the
+[Releases page](https://github.com/php-debugger/php-debugger/releases): a complete
+PHP **interpreter** with the debugger compiled in, and the **extension** on its own.
+Nothing is compiled on your machine, and no installer is involved — you download a
+file and put it somewhere.
+
+The catch is that you pick the right file yourself. Get it wrong and PHP either
+refuses to load the extension or fails to start.
+
+## Work out what you need
+
+Three things have to match your PHP: the **minor version**, the **thread safety**,
+and your **platform**.
+
+```bash
+php -v                          # 8.4.x -> you want the php8.4 files
+php -i | grep "Thread Safety"   # disabled -> nts,  enabled -> ts
+php-config --extension-dir      # where the extension has to go
+```
+
+`Thread Safety => disabled` means you want the `nts` files, which is what a normal
+CLI or PHP-FPM build is. `enabled` means `ts`.
+
+## File names
+
+Builds are published for PHP 8.2 to 8.5, thread-safe and not, on Linux, macOS and
+Windows, for both `arm64` and `x86_64`:
+
+| What | File |
+| --- | --- |
+| Interpreter | `php-php8.4-nts-linux-arm64` |
+| Interpreter (Windows) | `php-php8.4-nts-windows-x64.exe` |
+| Extension | `php-debugger-php8.4-nts-linux-arm64.so` |
+| Extension (Windows) | `php_php-debugger-php8.4-nts-windows-x64.dll` |
+
+Swap `8.4` for your PHP version, `nts` for `ts` if your build is thread-safe, and
+the platform for yours — `linux`, `macos` or `windows`, with `arm64` or `x86_64`
+(`x64` on Windows).
+
+## The interpreter
+
+A single self-contained file. Download it, make it executable, and run it:
+
+```bash
+curl -fsSL -o php-debugger \
+  https://github.com/php-debugger/php-debugger/releases/latest/download/php-php8.4-nts-linux-arm64
+chmod +x php-debugger
+./php-debugger -v
+```
+
+<ConsoleSample>{`PHP 8.4.23 (cli) (built: Jul  2 2026 20:39:24) (NTS)
+Copyright (c) The PHP Group
+Zend Engine v4.4.23, Copyright (c) Zend Technologies
+    with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
+
+Put it on your PATH if you want it to be the `php` you run. Nothing needs
+enabling — the debugger is compiled in, debugging is on by default, and every
+request starts a session.
+
+## The extension
+
+Download the `.so` into your extension directory, then load it from `php.ini`:
+
+```bash
+curl -fsSL -o "$(php-config --extension-dir)/php_debugger.so" \
+  https://github.com/php-debugger/php-debugger/releases/latest/download/php-debugger-php8.4-nts-linux-arm64.so
+```
+
+```ini
+zend_extension=php_debugger.so
+```
+
+It must be `zend_extension`, not `extension` — the debugger hooks into the engine
+and has to be registered as a Zend extension. Check it loaded:
+
+<ConsoleSample>{`$ php -v
+...
+    with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
+
+If PHP starts but the debugger is missing, or you get a "Zend Extension build ID"
+mismatch, the file does not match your PHP — check the version and thread safety
+again.
+
+:::note[On macOS]
+
+A file downloaded through a **browser** is quarantined, and Gatekeeper will refuse
+to run it. Downloading with `curl` as shown avoids that. If you did use a browser,
+clear the flag once:
+
+```bash
+xattr -d com.apple.quarantine ./php-debugger
+```
+
+:::
+
+## Staying up to date
+
+There is nothing to update these for you — download the newer file and replace the
+old one. The [installer](../installation.mdx) does this with `php-debugger update`
+if you would rather not track releases yourself.

docs/getting-started/install-options/from-source.mdx

@@ -0,0 +1,99 @@
+---
+title: Building from source
+---
+
+import ConsoleSample from '@site/src/components/ConsoleSample';
+
+:::warning[Try something else first]
+
+Every other option on this page gives you a build that has already been tested on
+the platform you are running. Building from source is the right answer when
+nothing else covers your platform, or when you are changing the debugger's code —
+not as a default.
+
+:::
+
+You can build either the **extension** on its own, which is the ordinary case, or a
+complete **PHP interpreter** with the debugger compiled into it.
+
+This page covers Linux and macOS. Windows uses a different toolchain and has its
+own page: [Building on Windows](./windows.mdx).
+
+Requires PHP 8.2 to 8.5. The build refuses to configure outside that range.
+
+## The extension
+
+You need PHP's development headers and a build toolchain: a compiler, `make`,
+`autoconf` and `libtool`. On Debian and Ubuntu that is `build-essential`,
+`autoconf`, `libtool` and `php-dev`; on Alpine you also need `linux-headers`,
+because the build uses `linux/rtnetlink.h`.
+
+```bash
+git clone https://github.com/php-debugger/php-debugger.git
+cd php-debugger
+
+phpize
+./configure --enable-php-debugger
+make -j$(nproc)
+```
+
+That leaves `modules/php_debugger.so`. Try it without installing anything:
+
+```bash
+php -d zend_extension=$PWD/modules/php_debugger.so -v
+```
+
+<ConsoleSample>{`PHP 8.4.23 (cli) (built: Jul  2 2026 20:39:24) (NTS)
+Copyright (c) The PHP Group
+Zend Engine v4.4.23, Copyright (c) Zend Technologies
+    with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies
+    with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
+
+To keep it, copy the file into your extension directory and load it from
+`php.ini`:
+
+```bash
+cp modules/php_debugger.so "$(php-config --extension-dir)/"
+```
+
+```ini
+zend_extension=php_debugger.so
+```
+
+Always `zend_extension`, never `extension` — the debugger hooks into the engine
+and has to be registered as a Zend extension.
+
+`phpize` uses whichever PHP is first on your PATH. If you have several installed,
+point the build at the right one with `./configure --with-php-config=/path/to/php-config`.
+
+## The interpreter
+
+Building PHP itself with the debugger linked in is what the prebuilt interpreter
+binaries and the Docker images are. You compile it as part of PHP rather than
+against it:
+
+```bash
+git clone --depth=1 --branch=PHP-8.4 https://github.com/php/php-src.git
+git clone https://github.com/php-debugger/php-debugger.git
+
+cp -r php-debugger php-src/ext/php_debugger
+mkdir -p php-src/m4 && cp php-debugger/m4/*.m4 php-src/m4/
+
+cd php-src
+./buildconf --force
+./configure --enable-php-debugger    # plus whatever else you need
+make -j$(nproc)
+```
+
+The result is `sapi/cli/php`, with the debugger reported by `php -v` and no
+extension to enable. The `./configure` line above is the minimum; a PHP you intend
+to actually use will want the usual complement of extensions and SAPIs.
+
+## If the build fails
+
+- **`not supported. Need a PHP version >= 8.0.0 and < 8.7.0`** — `phpize` picked up
+  a PHP outside the supported range. Check `php-config --version`.
+- **`rtnetlink.h` not found** — install your distribution's kernel headers
+  (`apk add linux-headers` on Alpine).
+- **PHP starts without the debugger** — you loaded it with `extension=` instead of
+  `zend_extension=`.

docs/getting-started/install-options/index.md

@@ -0,0 +1,40 @@
+---
+title: More install options
+---
+
+There is more than one way to get PHP Debugger onto a machine. They differ in how
+much work they are and in what you end up with — either a **self-contained PHP
+interpreter** with the debugger compiled in, or the **extension** loaded into a
+PHP you already have.
+
+If you have no particular reason to choose, use the [installer](../installation.mdx).
+
+| Option | Installs | Good for |
+| --- | --- | --- |
+| **[Installer](../installation.mdx)** | Either | Almost everyone. One command, and it can undo itself. |
+| **[Docker](../docker.mdx)** | Either | Containerised projects. |
+| **[PIE](./pie.mdx)** | Extension | Keeping the PHP you have, managed by a standard tool. |
+| **[Prebuilt binaries](./binaries.mdx)** | Either | No build tools, no installer — just a file to download. |
+| **[From source](./from-source.mdx)** | Either | A platform nothing else covers, or local changes to the code. |
+| **[From source on Windows](./windows.mdx)** | Either | The same, on Windows, where the toolchain differs. |
+
+## Which one gives me what
+
+The **interpreter** is a complete PHP with the debugger built into it. Nothing to
+enable, and it cannot be accidentally unloaded. The trade-off is that it replaces
+the `php` you run.
+
+The **extension** leaves your existing PHP in place and loads the debugger into
+it. That keeps whatever else you had configured, at the cost of a `zend_extension`
+line and matching a build to your exact PHP.
+
+## Notes before you pick
+
+- **Building from source is a last resort.** Every other option gives you a tested
+  build. Reach for it when nothing else covers your platform, or when you are
+  changing the code.
+- **The extension has to match your PHP exactly** — same minor version, same thread
+  safety, same architecture. The installer and PIE work that out for you; with
+  prebuilt binaries you match it yourself.
+- **Only the installer knows how to undo itself.** It backs up what it replaced and
+  restores it on `uninstall`. The other routes leave you to reverse them by hand.

docs/getting-started/install-options/pie.mdx

@@ -0,0 +1,66 @@
+---
+title: PIE
+---
+
+import ConsoleSample from '@site/src/components/ConsoleSample';
+
+[PIE](https://github.com/php/pie) — the PHP Installer for Extensions, from the PHP
+Foundation — is the standard way to install PHP extensions. It compiles the
+debugger against the PHP you already have and enables it for you.
+
+This installs the **extension**, not the interpreter. Your existing PHP stays
+exactly where it is.
+
+## Before you start
+
+PIE builds the extension on your machine, so you need a working build toolchain:
+a compiler, `make`, `autoconf`, `libtool`, and `unzip`. Most systems used for
+development already have these.
+
+## 1. Get PIE
+
+Skip this if you already have it. Full instructions are in the
+[PIE documentation](https://github.com/php/pie#installation); the short version is
+to download the phar and put it on your PATH:
+
+```bash
+curl -fsSL https://github.com/php/pie/releases/latest/download/pie.phar \
+    -o /usr/local/bin/pie
+chmod +x /usr/local/bin/pie
+```
+
+## 2. Install the debugger
+
+```bash
+pie install php-debugger/php-debugger
+```
+
+PIE resolves the latest release, compiles it against your PHP, installs the
+resulting `php_debugger.so` into your extension directory, and enables it. If
+build tools are missing it will tell you which ones, and `--auto-install-build-tools`
+lets it install them for you.
+
+## 3. Check it worked
+
+<ConsoleSample>{`$ php -v
+PHP 8.4.23 (cli) (built: Jul  2 2026 20:39:24) (NTS)
+Copyright (c) The PHP Group
+Zend Engine v4.4.23, Copyright (c) Zend Technologies
+    with Zend OPcache v8.4.23, Copyright (c), by Zend Technologies
+    with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}</ConsoleSample>
+
+The defaults need no configuration: debugging is on, every request starts a
+session, and the debugger connects on port 9003 whenever your IDE is listening.
+
+## Updating and removing
+
+`pie install` again to move to a newer release. To remove the extension, delete
+the `.ini` file PIE wrote and the `php_debugger.so` it installed —
+`php --ini` and `php-config --extension-dir` will tell you where both live.
+
+:::note[Want something that undoes itself?]
+
+The [installer](../installation.mdx) backs up whatever it replaces and restores it
+on `php-debugger uninstall`, which PIE does not do.
+
+:::