diff --git a/docs/agentic-debugging/agents.mdx b/docs/agentic-debugging/agents.mdx
new file mode 100644
index 00000000..6ba358e0
--- /dev/null
+++ b/docs/agentic-debugging/agents.mdx
@@ -0,0 +1,245 @@
+---
+title: Debugging with agents
+description: Add DBGP Client to Claude Code or any other MCP agent, and let it debug your PHP scripts and web requests.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+`dbgp mcp` runs DBGP Client as an [MCP](https://modelcontextprotocol.io) server.
+Once you add it to your agent, the agent can debug PHP the way you would in your
+IDE: set breakpoints, run the code, step through it, and look at the stack, the
+variables, the output and the warnings.
+
+## Add it to your agent
+
+
+
+
+```bash
+claude mcp add dbgp -- dbgp mcp
+```
+
+This adds it to the current project. Add `--scope user` to make it available in
+all of your projects:
+
+```bash
+claude mcp add --scope user dbgp -- dbgp mcp
+```
+
+Run `/mcp` inside Claude Code to check that it is connected.
+
+
+
+
+Any agent that supports MCP servers can use dbgp. Add a server that runs the
+command `dbgp` with the argument `mcp`. Most agents take a JSON configuration like
+this one:
+
+```json
+{
+ "mcpServers": {
+ "dbgp": {
+ "command": "dbgp",
+ "args": ["mcp"]
+ }
+ }
+}
+```
+
+See your agent's documentation for where its MCP settings live.
+
+
+
+
+The agent starts `dbgp mcp` itself when it needs it, so there is nothing else to
+run. [Options](#options) go after `mcp`, for example `dbgp mcp -no-eval`.
+
+## Make sure PHP can reach dbgp
+
+When a script or request starts, PHP Debugger
+[connects](../user-guide/connecting-to-a-client.md) to the address in
+`php_debugger.client_host` on the port in `php_debugger.client_port`. They default to `localhost` and `9003`, and dbgp listens
+on port `9003` by default. So when PHP runs on the same machine as your agent,
+there is nothing to set up.
+
+### PHP in a container or on a server
+
+PHP has to connect to the machine your agent runs on. Set `client_host` to an
+address that reaches it, such as `host.docker.internal` from a Docker container:
+
+```ini
+php_debugger.client_host=host.docker.internal
+```
+
+[Connecting to a client](../user-guide/connecting-to-a-client.md#when-the-code-runs-somewhere-else)
+covers the other ways to find that address.
+
+dbgp also needs to know where your project's files are inside the container, so
+that the files and lines the agent works with match the ones PHP runs. The agent
+can work this out and add the mapping itself, but if you always debug the same
+setup you can pass it with `-map`, as `LOCAL=REMOTE`:
+
+```bash
+claude mcp add dbgp -- dbgp mcp -map /home/you/myapp=/var/www/html
+```
+
+### If your IDE is listening too
+
+Only one program can listen on a port at a time. If your IDE is listening on
+`9003`, dbgp cannot, and PHP might connect to your IDE instead of to the agent.
+Stop listening in your IDE while the agent debugs.
+
+To use both at the same time, give dbgp a port of its own with `-php-port`, and set
+`client_port` to that port for the PHP the agent runs. For a script, the
+[`PHP_DEBUGGER_CONFIG`](../reference/environment-variables.md#php_debugger_config)
+environment variable does it for a single run:
+
+```bash
+PHP_DEBUGGER_CONFIG="client_port=9013" php app.php
+```
+
+## Ask it to debug something
+
+Tell the agent what is wrong and how to make it happen, and ask it to use the
+debugger. It decides where to put breakpoints, runs the code, and reports what it
+found. For example:
+
+> The total on the checkout page is wrong when a coupon is applied. Debug the
+> request to /checkout with a breakpoint in CartService::total() and find out why.
+
+> `php bin/console app:import users.csv` skips some of the rows. Use the debugger
+> to find out which ones, and why.
+
+> The test `testRefundIsCapped` fails. Debug it and step through `Refund::amount()`
+> to see where the value goes wrong.
+
+The more you tell it, the faster it gets there: the URL or command that shows the
+problem, what you expected to happen, and where you think the problem is. Asking
+it to *use the debugger* matters too: otherwise, many agents still reach for
+`var_dump()` out of habit.
+
+## What happens while it debugs
+
+dbgp does not listen for PHP until the agent asks it to, and stops when the agent
+is done. A typical run goes like this:
+
+1. The agent adds its breakpoints and starts listening.
+2. It runs the script, or sends the web request, in the background.
+3. PHP Debugger connects to dbgp, and the script waits there, stopped at its
+ start. The agent takes that session and runs it to the first breakpoint.
+4. It looks at the stack, the variables and the source, steps through the code, and
+ reads what the script has printed and the warnings it raised.
+5. When it has what it needs, it ends the session, removes its breakpoints and
+ stops listening.
+
+### Other requests while it listens
+
+PHP Debugger is always on, so while dbgp is listening, *every* script or request
+that runs connects to it, not just the agent's. If you load a page of your app in
+the browser while the agent is debugging, that request connects too, and waits.
+
+dbgp lets such requests go: a session that no agent takes within a minute of
+connecting is detached, and its script runs on to its end without the debugger. So
+nothing is left hanging, but a request you make while the agent is debugging can
+take up to a minute to answer.
+
+Agents keep their listening short, so this rarely comes up. When it does, it is
+usually a sign that the agent forgot to stop listening: ask it to.
+
+## The tools it gets
+
+These are the tools dbgp gives the agent. You do not need to know them to use it,
+but they show what it can and cannot do:
+
+| Tool | What it does |
+| --- | --- |
+| `status` | Shows whether dbgp is listening, the sessions, breakpoints and path mappings. |
+| `listen`, `unlisten` | Start and stop listening for PHP. |
+| `add_breakpoint`, `remove_breakpoint`, `breakpoints` | Manage breakpoints: on a line, optionally with a condition, when a function is called or returns, or when an exception is thrown. |
+| `add_path_mapping`, `path_mappings` | Map a project directory to where PHP sees it, for PHP in a container or on a server. |
+| `sessions`, `wait_for_session` | List the sessions, and wait for the next one to connect. |
+| `continue`, `wait_for_stop` | Run to the next breakpoint, or step into, over or out of the code. |
+| `stop`, `detach` | End a session where it is, or let its script run on without the debugger. |
+| `stack`, `variables`, `variable`, `variable_value` | Show the call stack and the variables of any frame, a page at a time for large arrays and objects. |
+| `source` | Show the source around where the code stopped, or around any file and line. |
+| `output`, `warnings` | Show what the script printed, and the PHP warnings and notices it raised. |
+| `eval`, `set_variable` | Evaluate a PHP expression in the stopped script, or change a variable. |
+
+## Options
+
+Add these after `dbgp mcp` in the command your agent runs:
+
+| Option | What it does |
+| --- | --- |
+| `-no-eval` | Turns off everything that runs PHP code written by the agent. See [Look, don't touch](#look-dont-touch). |
+| `-map LOCAL=REMOTE` | Maps a directory on this machine to where PHP sees it. Repeat it for several mappings. |
+| `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. |
+| `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. |
+| `-listen` | Listens for PHP from the start, instead of waiting for the agent to ask. |
+| `-mcp-port PORT` | The port agents connect to over MCP. Defaults to `9004`. |
+
+`dbgp mcp -h` lists them all.
+
+## Look, don't touch
+
+With `-no-eval`, the agent cannot run PHP code of its own in the script it is
+debugging. That turns off the `eval` and `set_variable` tools, and conditions on
+breakpoints. It can still stop the code anywhere, step through it, and read every
+variable, so it can still find out what went wrong. It just cannot change anything
+along the way.
+
+```bash
+claude mcp add dbgp -- dbgp mcp -no-eval
+```
+
+:::warning[It can still see everything]
+
+This limits what the agent can *do*, not what it can *see*: it still reads every
+variable the script has, passwords and API keys included. And PHP may still run some
+code when reading values: reading an object property that does not exist calls the
+object's `__get()` method, if it has one.
+
+:::
+
+## Sharing one dbgp between agents
+
+By default, each agent session starts its own dbgp, which goes away when the
+session ends, along with its breakpoints. To keep one running in the background
+instead, start it yourself:
+
+```bash
+dbgp mcp start # start it, with any of the options above
+dbgp mcp status # is it running?
+dbgp mcp stop # stop it
+```
+
+While it runs, agents that start `dbgp mcp` connect to it instead of starting their
+own, and use the options it was started with. That gives you:
+
+- **Breakpoints and sessions that last** from one agent session to the next.
+- **Several agents debugging at once**, sharing the same breakpoints and path
+ mappings. Each agent has its own current session, and dbgp keeps listening until
+ every agent that asked it to listen has stopped.
+
+Agents reach it on port `9004` by default, on this machine only. Change the port with
+`-mcp-port` when you start it. Only you can use it: agents connect with a token
+kept in a file that other users on the machine cannot read.
+
+It does not start again by itself after a restart, so run `dbgp mcp start` again
+when you need it. After [updating dbgp](./installation.mdx#updating), restart it
+to use the new version.
+
+## Using it with Xdebug
+
+dbgp works with Xdebug too. PHP Debugger starts debugging every request by itself,
+but Xdebug has to be told to:
+
+```ini
+xdebug.mode=debug
+xdebug.start_with_request=yes
+```
+
+Xdebug in debug mode slows every request down, even while nothing is listening.
+PHP Debugger costs almost nothing until something listens, which is what makes it
+the better fit for leaving on while an agent works.
diff --git a/docs/agentic-debugging/cli.mdx b/docs/agentic-debugging/cli.mdx
new file mode 100644
index 00000000..8e8f3785
--- /dev/null
+++ b/docs/agentic-debugging/cli.mdx
@@ -0,0 +1,285 @@
+---
+title: Debugging from the terminal
+description: Use DBGP Client as an interactive debugger in your terminal, to debug PHP scripts and web requests without an IDE.
+---
+
+`dbgp` on its own is an interactive debugger that runs in your terminal. It does
+everything you would do in an IDE: set breakpoints, step through the code, and look
+at the stack and the variables. You type commands at a prompt instead of clicking.
+
+That makes it handy wherever an IDE is not: on a server you reached over SSH,
+inside a container, or for a quick look at a script without opening a project.
+
+## Start it
+
+Run `dbgp`, optionally with a breakpoint or two:
+
+```bash
+dbgp -break src/Controller/HomeController.php:25
+```
+
+dbgp starts listening for PHP right away, on port `9003`, and waits for your
+commands. Then run your PHP code as usual, for example in another terminal:
+
+```bash
+php app.php
+```
+
+The script connects to dbgp and stops at its start, waiting for you. Web requests
+work the same way: load the page in your browser, or send the request with `curl`,
+and it connects too.
+
+As with an IDE, PHP finds dbgp through
+[`client_host` and `client_port`](../user-guide/connecting-to-a-client.md), which
+default to `localhost` and `9003`. When PHP runs on the same machine, there is
+nothing to set up.
+
+## A first session
+
+Here is a short script that adds up the items in a cart:
+
+```php title="cart.php"
+ 'Book', 'price' => 12.5, 'qty' => 2],
+ ['name' => 'Pen', 'price' => 1.2, 'qty' => '3'],
+];
+
+echo total($items, 5), "\n";
+```
+
+Start dbgp with a breakpoint inside the loop, then run `php cart.php` in another
+terminal. dbgp announces the session, and `run` takes it to the breakpoint, showing
+the code around it:
+
+```text
+$ dbgp -break cart.php:7
+Breakpoint 1: /home/you/shop/cart.php:7
+Listening for PHP on port 9003. Sessions are announced when PHP connects,
+and commands that need one wait for it. Type help for commands.
+(dbgp) run
+Waiting for PHP to connect (Ctrl-C to cancel)...
+
+[session 1 connected: /home/you/shop/cart.php (selected)]
+Stopped at /home/you/shop/cart.php:7
+ 3 function total(array $items, float $discount): float
+ 4 {
+ 5 $sum = 0;
+ 6 foreach ($items as $item) {
+=> 7 $sum += $item['price'] * $item['qty'];
+ 8 }
+ 9
+ 10 return $sum - $discount;
+ 11 }
+```
+
+The prompt now shows the session and its state: session `1`, stopped at a
+breakpoint. Look at how it got there, and at the variables:
+
+```text
+(dbgp 1:break) stack
+#0 total() at /home/you/shop/cart.php:7
+#1 {main}() at /home/you/shop/cart.php:18
+(dbgp 1:break) vars
+$discount float = 5
+$item array = array[3]
+$items array = array[2]
+$sum int = 0
+(print NAME shows what an array or object contains)
+(dbgp 1:break) print $item
+$item array = array[3]
+ $item["name"] string = "Book"
+ $item["price"] float = 12.5
+ $item["qty"] int = 2
+```
+
+`next` steps over the line. Here that goes round the loop and back to line 7, for
+the next item, with `$sum` updated:
+
+```text
+(dbgp 1:break) next
+Stopped at /home/you/shop/cart.php:7
+...
+(dbgp 1:break) print $sum
+$sum float = 25
+```
+
+`out` runs to the end of the function and stops back in the code that called it.
+`run` then runs the script to its end, `output` shows what it printed, and `stop`
+ends the session:
+
+```text
+(dbgp 1:break) out
+Stopped at /home/you/shop/cart.php:18
+...
+=> 18 echo total($items, 5), "\n";
+(dbgp 1:break) run
+Script finished; output shows its output, stop ends the session.
+(dbgp 1:stopping) output
+23.6
+(dbgp 1:stopping) stop
+Stopped session 1.
+(dbgp 1:ended)
+```
+
+dbgp keeps listening, so you can run the script again and the next session starts
+the same way. `quit` exits dbgp.
+
+## Breakpoints
+
+| Command | Stops |
+| --- | --- |
+| `break FILE:LINE` | At a line. |
+| `break LINE` | At a line of the file the session is stopped in. |
+| `break FILE:LINE if COND` | At a line, but only when the PHP expression `COND` is true. |
+| `break call FUNC` | When the function or method `FUNC` is called. |
+| `break return FUNC` | When the function or method `FUNC` returns. |
+| `break exception CLASS` | When an exception of class `CLASS`, or a subclass of it, is thrown. |
+
+A relative `FILE` is taken from the directory you started dbgp in. `breaks` lists
+the breakpoints with their numbers, and `delete ID` removes one. Breakpoints apply
+to every session, including ones that connect later.
+
+A conditional breakpoint is the quickest way to stop on the one case you are
+interested in, rather than every time round a loop:
+
+```text
+(dbgp) break cart.php:7 if $item["name"] == "Pen"
+Breakpoint 1: /home/you/shop/cart.php:7 if $item["name"] == "Pen"
+```
+
+To set breakpoints before PHP connects, either type them at the prompt or pass them
+with `-break` when you start dbgp. Repeat `-break` for several.
+
+## Running and stepping
+
+| Command | What it does |
+| --- | --- |
+| `run` | Runs to the next breakpoint, or to the end of the script. |
+| `step` | Steps into the next statement, going inside any function it calls. |
+| `next` | Steps over the next statement, running any function it calls in one go. |
+| `out` | Runs to the end of the current function, and stops in the code that called it. |
+
+While the script runs, these commands wait for it to stop. Press `Ctrl-C` to stop
+waiting and get the prompt back: the script keeps running.
+
+When the script reaches its end, the session stays open so that you can still read
+its output. `stop` then ends it.
+
+## Looking around
+
+| Command | What it shows |
+| --- | --- |
+| `stack` | The call stack, innermost first. |
+| `vars [DEPTH [CONTEXT]]` | The variables of a stack frame: `0`, the default, is where the code stopped, `1` the function that called it, and so on. |
+| `contexts` | The variable contexts `vars` can show: the local variables, the superglobals, and the constants you defined. |
+| `print NAME` | A variable, and what an array or object contains, such as `print $user["name"]` or `print $order->items`. `-d DEPTH` reads it from another stack frame, and `-p PAGE` shows further pages of a large array or object. |
+| `value NAME` | A variable's whole value, for long strings that `print` cuts short. Also takes `-d DEPTH`. |
+| `source [[FILE:]LINE]` | The source around where the code stopped, or around another line or file. |
+| `output` | What the script has printed since you last looked. |
+| `notes` | The PHP warnings, notices and other errors the script has raised since you last looked. |
+
+## Changing things
+
+| Command | What it does |
+| --- | --- |
+| `eval CODE` | Evaluates a PHP expression where the code stopped, and shows the result. |
+| `set NAME = EXPR` | Sets a variable to the value of a PHP expression. |
+
+`eval` is handy for checking an expression before you change the code:
+
+```text
+(dbgp 1:break) eval $item["price"] * $item["qty"]
+3.5999999999999996 (float)
+```
+
+Both run code in the script you are debugging, so they can change what it does
+from there on.
+
+## Ending a session
+
+`stop` ends the script where it is. `detach` lets it run on to its end without the
+debugger, which is what you want for a web request whose page you still want to
+see.
+
+## Several sessions at once
+
+Every script or request that connects while dbgp is listening becomes a session.
+dbgp announces each one as it connects, and selects the first, so commands act on
+it.
+
+```text
+[session 2 connected: /home/you/shop/public/index.php]
+```
+
+`sessions` lists them all, and `use ID` switches to another one.
+
+A session waits for you until you run, detach or stop it. PHP Debugger is always
+on, so while dbgp listens, every request you make to your app connects and waits,
+not just the one you meant to debug. When you have the session you want, `unlisten`
+stops dbgp from taking new ones, and those requests run without the debugger again.
+`listen` starts taking them again.
+
+## PHP in a container or on a server
+
+PHP has to connect to the machine dbgp runs on. Set `client_host` to an address that
+reaches it, such as `host.docker.internal` from a Docker container. See
+[Connecting to a client](../user-guide/connecting-to-a-client.md#when-the-code-runs-somewhere-else)
+for the details.
+
+dbgp also needs to know where your project's files are inside the container, so
+that breakpoints you set on your files land on the files PHP runs. Pass the mapping
+as `LOCAL=REMOTE` with `-map` when you start dbgp:
+
+```bash
+dbgp -map /home/you/shop=/var/www/html -break src/Cart.php:42
+```
+
+or add it at the prompt with `map`. `maps` lists the mappings.
+
+You can also run dbgp on the server or in the container itself, next to PHP, over
+SSH or with `docker exec`. Then PHP connects to `localhost` as usual, and no mapping
+is needed.
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `-break FILE:LINE` | Sets a breakpoint before PHP connects. Repeat it for several. |
+| `-map LOCAL=REMOTE` | Maps a directory on this machine to where PHP sees it. Repeat it for several. |
+| `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. |
+| `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. |
+| `-history FILE` | Where to keep the command history. Defaults to `~/.dbgp_history`. Set it to an empty value to keep none. |
+| `-version` | Prints the version and exits. |
+
+`dbgp -h` lists them all.
+
+## At the prompt
+
+The prompt has line editing, tab completion for commands, and a history you can
+step through with the arrow keys, kept between runs. `help` lists every command.
+
+The most common commands have short aliases:
+
+| Alias | Command |
+| --- | --- |
+| `r` | `run` |
+| `s` | `step` |
+| `n` | `next` |
+| `o` | `out` |
+| `b` | `break` |
+| `bt` | `stack` |
+| `p` | `print` |
+| `l` | `source` |
+| `q`, `exit` | `quit` |
diff --git a/docs/agentic-debugging/dbgp-client.mdx b/docs/agentic-debugging/dbgp-client.mdx
new file mode 100644
index 00000000..c43ad55c
--- /dev/null
+++ b/docs/agentic-debugging/dbgp-client.mdx
@@ -0,0 +1,117 @@
+---
+title: DBGP Client
+description: DBGP Client lets AI agents debug PHP with PHP Debugger, the way you would. It also works as a standalone debugger in your terminal.
+---
+
+import DbgpDiagram from '@site/src/components/DbgpDiagram';
+
+[DBGP Client](https://github.com/php-debugger/dbgp-client) is a debugger client for
+PHP. Its `dbgp` command speaks [DBGp](../reference/debug-protocol.md), the same
+protocol your IDE uses to talk to PHP Debugger, and it can be used in two ways:
+
+- **As a debugging tool for AI agents.** `dbgp mcp` is an
+ [MCP](https://modelcontextprotocol.io) server that lets an agent such as Claude
+ Code debug PHP the way you would: set breakpoints, run the code, step through it,
+ and look at the stack, variables, output and warnings.
+- **As a command-line debugger.** `dbgp` on its own is an interactive debugger in
+ your terminal, for when you want to debug PHP yourself without an IDE.
+
+Both work with PHP scripts and web requests, on your own machine, in a container or
+on a server.
+
+## Why let an agent use a debugger?
+
+Ask a coding agent to find out why something is broken and it will usually do one of
+two things. It reads the code and reasons about what *should* happen, which works
+until the bug is in something it cannot see: the data in your database, a value
+from the request, a config setting, the order in which things actually ran. Or it
+adds `var_dump()` and log lines, runs the code, reads the output, adds some more, and
+eventually has to remember to take them all out again.
+
+That second approach is the one [we tell people to stop using](../user-guide/stop-using-dd.md),
+and the reasons are the same for an agent. Every round adds code you did not ask for,
+each run shows only what it decided to print beforehand, and anything it forgot to
+print means another round.
+
+With a debugger, the agent stops the code where it wants to look and sees everything:
+the real values of every variable, the call stack that led there and the path the
+code actually took. It does not have to guess what to print, and there is nothing to
+clean up afterwards, because your code is never changed.
+
+## Why it pairs well with PHP Debugger
+
+An agent debugs in short bursts, between long stretches of reading and editing code.
+For most of that time nothing is being debugged, so the debugger should cost nothing
+then.
+
+That is how PHP Debugger works: it can stay on all the time and costs almost nothing
+until something is listening. dbgp only listens while the agent is actually
+debugging, and stops when it is done. You can leave both of them set up permanently,
+and PHP runs at full speed except while the agent is stepping through it.
+
+dbgp also works with Xdebug. Run `php -v` to see which one your PHP has.
+
+## What an agent can do with it
+
+dbgp gives the agent the same tools you have in your IDE:
+
+- **Breakpoints** on a line, optionally with a condition, when a function is called
+ or returns, or when an exception is thrown
+- **Running and stepping**: run to the next breakpoint, or step into, over and out
+ of the code
+- **The call stack and variables** in any frame, including large arrays and objects
+ a page at a time
+- **The source** around where the code stopped
+- **What the script printed** and the **PHP warnings and notices** it raised
+- **Evaluating PHP expressions** and **changing variables** in the stopped script
+- **Path mappings** for PHP running in a container or on another machine
+
+The agent also starts the code to debug on its own, running a script or sending a
+web request, so you only have to tell it what is wrong. For example:
+
+> Find out why the total on the checkout page is wrong: debug the request to
+> /checkout with a breakpoint in CartService::total().
+
+## How it works
+
+dbgp sits between the agent and PHP. The agent talks to dbgp over MCP, and dbgp
+talks to PHP Debugger over DBGp:
+
+
+
+A typical debugging run goes like this:
+
+1. The agent adds a breakpoint and tells dbgp to start listening.
+2. It runs the script or sends the request. PHP Debugger connects to dbgp, and the
+ script waits there.
+3. The agent runs the code to the breakpoint, and looks at the stack, the variables
+ and the source.
+4. It steps through the code, or runs on to another breakpoint, until it has found
+ what it was looking for.
+5. It ends the session, removes the breakpoint and stops listening, and PHP runs at
+ full speed again.
+
+Each script run or request that connects is a separate session, so the agent can
+debug several at a time, for example a web request and the queue job it sets off.
+
+:::warning[Security]
+
+Like any debugger, dbgp trusts the PHP that connects to it and the agent that uses
+it:
+
+- **The agent sees what your code sees.** While debugging, an agent can read every
+ variable of the script, including passwords and API keys, and any file PHP can
+ read. Start dbgp with `-no-eval` to stop the agent from running PHP code of its own
+ in the script, so it can only look. This does not hide anything from it.
+- **The PHP port is not authenticated.** Anything that can reach port `9003` can
+ connect to dbgp as if it were PHP, and show the agent made-up code and values. Make
+ sure only your own PHP hosts and containers can reach it, and use an SSH tunnel or
+ a VPN to debug PHP across a network you do not trust.
+
+:::
+
+## Next steps
+
+- [Install DBGP Client](./installation.mdx)
+- [Debug with your AI agent](./agents.mdx)
+- [Debug from the terminal](./cli.mdx)
diff --git a/docs/agentic-debugging/installation.mdx b/docs/agentic-debugging/installation.mdx
new file mode 100644
index 00000000..c1e6aa5a
--- /dev/null
+++ b/docs/agentic-debugging/installation.mdx
@@ -0,0 +1,164 @@
+---
+title: Installation
+description: Install DBGP Client on Linux, macOS or Windows, and check that PHP is ready to be debugged.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ConsoleSample from '@site/src/components/ConsoleSample';
+
+DBGP Client is a single program, `dbgp`, with nothing to install alongside it. The
+install script downloads the right build for your system and puts it on your
+`PATH`.
+
+:::info[Install it where your agent runs]
+
+dbgp runs on the machine where your agent, or your terminal, runs. If PHP runs in
+a container or on a server, you do not need to install dbgp there: PHP connects
+to it over the network.
+
+:::
+
+## Install it
+
+
+
+
+```bash
+curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh
+```
+
+This installs `dbgp` to `/usr/local/bin`. If you cannot write there, the script
+uses `sudo` and asks for your password.
+
+
+
+
+Run this in PowerShell as administrator:
+
+```powershell
+powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex"
+```
+
+This installs `dbgp` to `%ProgramFiles%\dbgp` and adds that folder to the system
+`PATH`. Open a new terminal afterwards so it picks up the change.
+
+
+
+
+### Choosing where and what to install
+
+Two environment variables change what the script does:
+
+| Variable | What it does |
+| --- | --- |
+| `INSTALL_DIR` | Installs to this directory instead. |
+| `VERSION` | Installs this release, such as `0.1.1`, instead of the latest one. |
+
+For example, to install into your home directory, where no administrator rights
+are needed:
+
+
+
+
+```bash
+curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | INSTALL_DIR="$HOME/.local/bin" sh
+```
+
+If the directory is not on your `PATH`, the script prints the line to add to your
+shell's profile.
+
+
+
+
+```powershell
+$env:INSTALL_DIR = "$env:LOCALAPPDATA\dbgp"
+powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex"
+```
+
+With `INSTALL_DIR` set, the script adds the directory to your own `PATH` rather
+than the system one.
+
+
+
+
+### Other platforms
+
+Builds are published for Linux and macOS, on both `amd64` and `arm64`, and for
+Windows on `amd64`. On anything else, install it with Go 1.26 or later:
+
+```bash
+go install github.com/php-debugger/dbgp-client/cmd/dbgp@latest
+```
+
+### Downloading it yourself
+
+You can also download the archive for your system from the
+[Releases page](https://github.com/php-debugger/dbgp-client/releases) and put the
+`dbgp` binary anywhere on your `PATH`. Each release file has a build provenance
+attestation, which shows it was built by the project's own release workflow. To
+check a file you downloaded, run:
+
+```bash
+gh attestation verify dbgp-linux-amd64.tar.gz --repo php-debugger/dbgp-client
+```
+
+## Check that it works
+
+```bash
+dbgp -version
+```
+
+This prints `dbgp` followed by the version you installed.
+
+## Make sure PHP can be debugged
+
+dbgp debugs PHP through PHP Debugger, or through Xdebug, so PHP needs one of them.
+Run `php -v` and look for PHP Debugger in the output:
+
+{`$ 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 PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`}
+
+If it is not there, [install PHP Debugger](../getting-started/installation.mdx)
+first.
+
+## Updating
+
+Run the install command again to update to the latest release. Set `VERSION` to
+move to a particular one, including an older one.
+
+If you run dbgp's MCP server in the background, it keeps running the version it
+started with. Restart it to use the new one:
+
+```bash
+dbgp mcp stop && dbgp mcp start
+```
+
+On Windows, stop it with `dbgp mcp stop` before updating: a running `dbgp` cannot be
+replaced.
+
+## Uninstalling
+
+Stop the background MCP server if you started one, then delete the `dbgp` binary:
+
+
+
+
+```bash
+dbgp mcp stop
+sudo rm /usr/local/bin/dbgp
+```
+
+
+
+
+Run `dbgp mcp stop`, delete the `%ProgramFiles%\dbgp` folder, and remove it from the
+system `PATH`.
+
+
+
+
+Remember to remove `dbgp` from your agent's MCP settings too.
diff --git a/docs/index.mdx b/docs/index.mdx
index 85f76162..6f19704f 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -2,7 +2,7 @@
id: home
slug: /
title: PHP Debugger
-description: Zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down.
+description: Agentic zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down. Built for you and your AI agents.
displayed_sidebar: docsSidebar
hide_title: true
hide_table_of_contents: true
diff --git a/docusaurus.config.js b/docusaurus.config.js
index d9586834..6e1cdd55 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -45,7 +45,7 @@ async function latestDebuggerVersion() {
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'PHP Debugger',
- tagline: 'Zero-overhead debugging for PHP',
+ tagline: 'Agentic zero-overhead debugging for PHP',
favicon: 'img/favicon.svg',
future: {
diff --git a/sidebars.js b/sidebars.js
index 91dde172..c3192c4d 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -43,6 +43,17 @@ const sidebars = {
'user-guide/troubleshooting',
],
},
+ {
+ type: 'category',
+ label: 'Agentic debugging',
+ collapsed: false,
+ items: [
+ 'agentic-debugging/dbgp-client',
+ 'agentic-debugging/installation',
+ 'agentic-debugging/agents',
+ 'agentic-debugging/cli',
+ ],
+ },
{
type: 'category',
label: 'Reference',
diff --git a/src/components/DbgpDiagram/index.js b/src/components/DbgpDiagram/index.js
new file mode 100644
index 00000000..87a39fc7
--- /dev/null
+++ b/src/components/DbgpDiagram/index.js
@@ -0,0 +1,79 @@
+import styles from './styles.module.css';
+
+const iconProps = {
+ width: 26,
+ height: 26,
+ viewBox: '0 0 24 24',
+ fill: 'none',
+ stroke: 'currentColor',
+ strokeWidth: 1.8,
+ strokeLinecap: 'round',
+ strokeLinejoin: 'round',
+ 'aria-hidden': true,
+};
+
+function Box({icon, title, text, highlight}) {
+ return (
+
+
+
+
+
+
+
+ ),
+ },
{
title: 'Fast & Lightweight',
text: 'Built for speed with zero performance overhead.',
@@ -32,16 +44,6 @@ const features = [
),
},
- {
- title: 'IDE Integration',
- text: 'Works seamlessly with your favorite IDE.',
- icon: (
-
- ),
- },
{
title: 'Always Available',
text: 'Leave it on. It costs almost nothing until you debug.',
diff --git a/src/components/HomeHero/index.js b/src/components/HomeHero/index.js
index c5a78dc6..3e877aad 100644
--- a/src/components/HomeHero/index.js
+++ b/src/components/HomeHero/index.js
@@ -16,10 +16,10 @@ export default function HomeHero() {
{`v${siteConfig.customFields.debuggerVersion}`}
- Zero-overhead debugging for PHP
+ Agentic zero-overhead debugging for PHP
- A lightweight, powerful debugger that doesn't slow you down.
+ A lightweight, powerful debugger that doesn't slow you down. Built for you and your AI agents.