Add astro dev --background to CLI reference

[matthewp]

Description (required)

Adds documentation for the new astro dev --background flag and astro dev stop, astro dev status, and astro dev logs subcommands for managing background dev servers. Also documents the /_astro/status health endpoint and automatic agent detection behavior.

Related issues & labels (optional)

• Implementation PR: Background dev server for AI coding agents astro#16610
• RFC: Background dev server roadmap#1362

This is for Astro 7.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	711423c
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6a189a143bdd490008f547df
😎 Deploy Preview	https://deploy-preview-13949--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/build-with-ai.mdx	Source changed, localizations will be marked as outdated.
en/reference/cli-reference.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

Thanks, the content looks good to me! My only concern is the organization:

We are mixing flags, subcommands and "general" information.

Because this is a reference page, maybe we can organize it this way to be consistent:

h2: astro dev
  h3: Flags
    h4: --background
  h3: Subcommands
    h4: astro dev stop
    h4: astro dev status
    h4: astro dev log
      h5: Flags
        h6: --follow

And "Background mode for AI coding agents" might be more helpful on https://docs.astro.build/en/guides/build-with-ai/ with a link to the reference for the available flags and subcommands?

Remains "Health endpoint"... unless you can think of another use case than AI, maybe this also belong to https://docs.astro.build/en/guides/build-with-ai/

[ArmandPhilippot]

The wording sounds a bit unnecessarily verbose ("this is the flag that is..."):

Suggested change

	Starts the dev server as a detached background process. This is the flag that is used automatically when an AI agent is detected, but it can also be used manually.
	Starts the dev server as a detached background process. This flag is provided automatically when an AI agent is detected. You can also use it manually:

But, if we move "Background mode for AI coding agents" to the "Build with AI" page, the second sentence should probably link to /en/guides/build-with-ai/#background-mode-for-ai-coding-agents.

[ArmandPhilippot]

Ah, and it seems this is already a bit outdated, but it would be nice to update the latest code snippet in https://docs.astro.build/en/reference/cli-reference/#astro-commands to reflect what pnpm dev --help actually prints now that the format (options/subcommands) is also changing.

[matthewp]

@ArmandPhilippot reorganized

[ArmandPhilippot]

Just a nit to keep the TOC consistent:

Otherwise, LGTM!