@nocobase/plugin-ai 2.1.0-beta.46 → 2.1.0-beta.47

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/caddy.md

@@ -1,158 +1,289 @@
-# Caddy
+---
+title: "Caddy"
+description: "Use nb proxy caddy to generate and manage Caddy reverse-proxy configuration for CLI-managed NocoBase envs."
+keywords: "NocoBase,nb proxy caddy,reverse proxy,Caddy,production"
+---
 
-If you already have a domain and want to get HTTPS running quickly, Caddy is usually the easiest choice. Compared with maintaining Nginx certificate config yourself, Caddy is more like the shortcut path for getting the entry layer online first.
+# Caddy
 
-The default recommendation is to run `nb env proxy caddy` directly.
+If you already have a domain and want to get HTTPS running quickly, `nb proxy caddy` is usually the simplest entry path.
 
-## When Caddy is usually the better fit
+Compared with maintaining certificate configuration in Nginx yourself, Caddy is more like the default shortcut for getting the entry layer online quickly.
 
-These cases usually favor Caddy first:
+## When Caddy is the better fit
 
-- You already have a domain and want HTTPS quickly
-- You do not want to maintain too many certificate and TLS details yourself
-- You only need a simple and stable entry layer
+In practice, Caddy is usually the better choice when:
 
-If you already use Nginx across the server to manage many sites, or you still need heavier caching, access control, and custom rules, [Nginx](./nginx.md) is usually the better fit.
+- you already have a domain and want to get HTTPS online quickly
+- you do not want to manage many certificate and TLS details yourself
+- you mainly want a simple and stable entry layer
 
-## Default path: let the CLI generate the Caddy config
+If you already use Nginx to manage many sites on the same server, or you still need heavier caching, access control, or custom rules, [Nginx](./nginx.md) is usually the better fit.
 
-If your app has already been saved as a CLI env and the env type is `local` or `docker`, the default recommendation is still to let the CLI generate the config. That way, routing details related to NocoBase paths, WebSocket handling, and subpaths stay managed by the CLI, and you only need to care about the site entry itself.
+## Recommended order: choose a driver, generate config, then start
 
-The most direct form is:
+For a CLI-managed env of type `local` or `docker`, the default order is:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com
+nb proxy caddy use docker
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-If you have already switched to the current env, you can also omit `--env`:
+Or with a local process:
 
 ```bash
-nb env proxy caddy --host demo.example.com
+nb proxy caddy use local
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-If you also want to specify the entry port, add it at the same time:
+Common follow-up commands are:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com --port 8080
+nb proxy caddy current
+nb proxy caddy status
+nb proxy caddy info
+nb proxy caddy reload
+nb proxy caddy restart
+nb proxy caddy stop
 ```
 
-`--host` is important here. Caddy decides whether to manage HTTPS based on the site address. In production, try to pass a domain that already resolves to the current server.
+In most cases:
 
-### Which files the CLI generates
+- `current` is the quickest way to confirm the active runtime driver
+- `status` shows whether Caddy is currently running normally
+- `info` shows the current config path, runtime root, and related runtime details
+- after regenerating config, `reload` is usually the first command to use
+- use `restart` when you need a full restart
 
-If you do not pass `--output`, the Caddy provider keeps three layers of files under `~/.nocobase/proxy/caddy/<env>/`:
+## What `generate` needs as input
 
-| File | Purpose |
-| --- | --- |
-| `generated.caddy` | The actual reverse-proxy config managed by the CLI and overwritten every time you run `nb env proxy caddy` |
-| `app.caddy` | Editable site entry file where you can add site-level config |
-| `~/.nocobase/proxy/caddy/nocobase.caddy` | Shared main config that imports every env `app.caddy` |
+The most common form is:
 
-Where:
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+```
 
-- `generated.caddy` is only meant to be managed by the CLI and should not be edited manually
-- `app.caddy` is editable, but you should keep the generated import inserted by the CLI
-- `nocobase.caddy` is mainly used by `--install`
+If you also want to specify the entry port:
 
-:::warning Note
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com --port 8080
+```
 
-If you need to add site-level Caddy config such as extra headers, authentication, rate limiting, or compression rules, edit `app.caddy`. `generated.caddy` will be overwritten the next time you run `nb env proxy caddy`.
+Where:
 
-:::
+- `--env`: which CLI env to generate config for
+- `--host`: the public domain name
+- `--port`: the proxy entry port
 
-### Install the shared config into Caddy and reload it
+For Caddy, `--host` matters especially because the site address strongly affects the HTTPS workflow. In production, it is usually best to pass a domain that already resolves to the current server.
 
-If you want the CLI to connect the shared config to the Caddy main config and immediately validate and reload Caddy, run:
+If the command says the env is missing `appPort`, save it first with:
 
 ```bash
-nb env proxy caddy --env demo --host demo.example.com --install --reload
+nb env update test2 --app-port 56575
 ```
 
-These flags are split like this:
+If you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`.
 
-- `--install` connects `~/.nocobase/proxy/caddy/nocobase.caddy` to the Caddy main config
-- `--reload` validates the config first and then reloads Caddy
+## Files maintained by the CLI
 
-If your Caddy executable is not on the default path, set the CLI config first:
+Using `test2` as an example, the Caddy workflow usually maintains:
 
-```bash
-nb config set bin.caddy /usr/bin/caddy
-```
+| Path | Purpose |
+| --- | --- |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/app.caddy` | CLI-generated full site config |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/nocobase.caddy` | Provider-level Caddy entry file that imports all env `app.caddy` files |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v1.html` | v1 SPA fallback page |
+| `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v2.html` | v2 SPA fallback page |
+| `NB_CLI_ROOT/test2/storage/dist-client` | Frontend build output for the current app |
+| `NB_CLI_ROOT/test2/storage/uploads` | Uploads directory for the current app |
 
-### When should you change `proxy.nb-cli-root`
+Where:
 
-Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Caddy runs in another container, mount root, or path view and cannot see the current user's `~/.nocobase` path.
+- files under `NB_CLI_ROOT/.nocobase/proxy/caddy/...` are CLI-managed proxy helper files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application itself
+- `nocobase.caddy` is the provider-level entry file and usually does not need manual edits
+- `app.caddy` is the full site config for one env and is overwritten as a whole when you regenerate it
 
-For example, if Caddy sees that path as `/workspace/.nocobase/...` inside a container, set:
+:::warning Note
 
-```bash
-nb config set proxy.nb-cli-root /workspace
-nb env proxy caddy --env demo --install --reload
-```
+If you need site-level Caddy config such as extra headers, authentication, rate limiting, or compression policy, you can adjust `app.caddy` as the baseline. But remember that running `generate` again overwrites that file.
 
-If you only want to preview the generated result, use:
+:::
 
-```bash
-nb env proxy caddy --env demo --print
-```
+## Handwritten config: when you are not using the CLI
 
-If you want to write the generated route fragment to a custom file, use:
+If the app is not CLI-managed, or you intentionally want to maintain the full Caddy config yourself, you can still write it by hand.
 
-```bash
-nb env proxy caddy --env demo --output ./generated.caddy
-```
+For NocoBase, though, a production entry is usually more than a simple `reverse_proxy`. In addition to forwarding API requests to the backend app, a complete Caddy config usually needs to handle uploads, frontend assets, `.well-known` routes, WebSocket, and SPA fallback pages together.
+
+Using `test2` as the example, the key Caddy-related paths usually include:
 
-For the full parameter reference, see [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md).
+- SPA fallback directory: `NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public`
+- Frontend build output: `NB_CLI_ROOT/test2/storage/dist-client`
+- Uploads directory: `NB_CLI_ROOT/test2/storage/uploads`
 
-## Handwritten config: what to do without the CLI
+In other words, a handwritten config usually needs to cover at least these entry areas:
 
-If your app is not managed by the CLI, or you explicitly want to maintain the full `Caddyfile` yourself, start with this minimal version:
+- `v`: redirect `/v` to `/v/`
+- `uploads`: expose the uploads directory
+- `dist`: expose the frontend build output
+- `oauth well-known`: handle the OAuth discovery path
+- `openid well-known`: handle the OpenID discovery path
+- `api`: forward `/api/` requests to the backend app
+- `ws`: forward WebSocket requests to the backend app
+- `spa v2`: serve `/v/` with the v2 entry and fallback page
+- `spa v1`: serve `/` with the v1 entry and fallback page
+
+So a complete Caddy config is usually more than a generic example such as:
 
 ```text
 your-domain.com {
-  encode zstd gzip
   reverse_proxy 127.0.0.1:13000
 }
 ```
 
-Where:
+For a CLI-managed app such as `test2`, a more realistic deployment structure usually looks closer to this:
+
+```text
+c.local.nocobase.com {
+    encode zstd gzip
+
+    handle /v {
+        redir * /v/ 302
+    }
+
+    handle_path /storage/uploads/* {
+        root * NB_CLI_ROOT/test2/storage/uploads
+        header Cache-Control public
+        header X-Content-Type-Options nosniff
+        file_server
+    }
+
+    handle_path /dist/* {
+        root * NB_CLI_ROOT/test2/storage/dist-client
+        header Cache-Control public
+        file_server
+    }
+
+    @oauth path_regexp oauth ^/\\.well-known/oauth-authorization-server/(.+)$
+    handle @oauth {
+        rewrite * /{re.oauth.1}/.well-known/oauth-authorization-server
+        reverse_proxy host.docker.internal:56575
+    }
+
+    @openid path_regexp openid ^/\\.well-known/openid-configuration/(.+)$
+    handle @openid {
+        rewrite * /{re.openid.1}/.well-known/openid-configuration
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle /api/* {
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle /ws {
+        reverse_proxy host.docker.internal:56575
+    }
+
+    handle_path /v/* {
+        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
+        header Cache-Control "no-store, no-cache, must-revalidate"
+        header X-Robots-Tag "noindex, nofollow"
+        try_files {path} /index-v2.html
+        file_server
+    }
+
+    handle_path /* {
+        root * NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public
+        header Cache-Control "no-store, no-cache, must-revalidate"
+        header X-Robots-Tag "noindex, nofollow"
+        try_files {path} /index-v1.html
+        file_server
+    }
+}
+```
+
+Two details matter here:
 
-- Replace `your-domain.com` with your domain
-- Replace `127.0.0.1:13000` with the real address your NocoBase app listens on
+- files under `NB_CLI_ROOT/.nocobase/proxy/caddy/...` are CLI-managed SPA fallback files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application's own build output and uploads
+
+If the app uses subpath deployment, or if frontend assets, uploads, and the entry layer do not share the same path view, handwritten config becomes easier to get wrong. In those cases, it is usually safer to generate the config first with:
+
+```bash
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+```
 
-If the domain already resolves to the current server correctly, Caddy usually handles HTTPS certificate issuance and renewal automatically.
+Then use the generated result as the baseline for manual adjustments.
 
-If you do not have a domain yet and only want to verify the reverse-proxy chain first, you can listen on a port:
+If you want the CLI to get the routes and paths working first, the generated structure usually looks like this:
 
 ```text
-:80 {
-  reverse_proxy 127.0.0.1:13000
-}
+NB_CLI_ROOT/.nocobase/proxy/caddy/nocobase.caddy
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/app.caddy
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v1.html
+NB_CLI_ROOT/.nocobase/proxy/caddy/test2/public/index-v2.html
+NB_CLI_ROOT/test2/storage/dist-client
+NB_CLI_ROOT/test2/storage/uploads
 ```
 
-In production, though, it is still better to switch to a domain-based site address as soon as possible so Caddy can also take over HTTPS.
+Where:
+
+- `nocobase.caddy` imports all `*/app.caddy` files
+- `test2/app.caddy` is the full site config for env `test2`
+- `public/index-v1.html` and `public/index-v2.html` are CLI-generated SPA fallback pages
+
+The safer workflow is usually:
+
+1. let the CLI generate the Caddy config first
+2. use the generated output to confirm the routing structure and real filesystem paths
+3. then adjust it for your own domain, runtime driver, and mount layout
 
-If your app is not mounted at `/` but under a subpath, handwritten Caddy config also means you need to confirm application variables such as `APP_PUBLIC_PATH` and `WS_PATH`. In that case, it is usually easier to go back to `nb env proxy caddy` and let the CLI generate the config.
+That is usually less error-prone than writing the full config from scratch.
 
 ## Validate and reload the config
 
+If you write or adjust Caddy config manually, validate it first and then reload:
+
 ```bash
 caddy validate --config /etc/caddy/Caddyfile
 systemctl reload caddy
 ```
 
-If you do not manage Caddy with `systemd`, use your own startup and reload workflow.
+If you are not using `systemd` to manage Caddy, replace that with your own start and reload workflow.
+
+If you manage the entry layer through `nb proxy caddy`, the usual first choice is:
+
+```bash
+nb proxy caddy reload
+```
+
+If you want to inspect the current driver, main config-file path, runtime root, and container or local binary details, run:
+
+```bash
+nb proxy caddy info
+```
+
+If you only want to confirm whether Caddy is already running, run:
+
+```bash
+nb proxy caddy status
+```
 
-## Notes
+## Common notes
 
-- `nb env proxy caddy` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
-- If the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
-- `--output` and `--print` are useful for preview or custom integration, but they do not additionally create `app.caddy` or the shared main config
-- If you already have a domain that resolves correctly to the server, Caddy is often the fastest way to get HTTPS working
+- `nb proxy caddy generate` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
+- if the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
+- if you already have a domain that resolves correctly to the current server, Caddy is often the fastest way to get HTTPS
+- if you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`
 
 ## Related links
 
-- [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
-- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Reverse Proxy in Production](./index.md)
+- [Nginx](./nginx.md)
+- [Install with the CLI](../../installation/cli.md)
 - [Install with Docker Compose](../../installation/docker-compose.md)
-- [App Environment Variables](../../installation/env.md)
+- [Environment variables](../../installation/env.md)

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/index.md

@@ -1,69 +1,94 @@
 ---
-title: 'Reverse Proxy for Production'
-description: 'Use nb env proxy nginx and nb env proxy caddy to generate reverse-proxy configs for CLI-managed NocoBase envs.'
-keywords: 'NocoBase,nb env proxy nginx,nb env proxy caddy,reverse proxy,Nginx,Caddy,production'
+title: "Reverse Proxy in Production"
+description: "Use nb proxy nginx and nb proxy caddy to generate and manage reverse-proxy configuration for CLI-managed NocoBase envs."
+keywords: "NocoBase,nb proxy nginx,nb proxy caddy,reverse proxy,Nginx,Caddy,production"
 ---
 
-# Reverse Proxy for Production
+# Reverse Proxy in Production
 
-In NocoBase CLI, there are two recommended entry points for putting a reverse proxy in front of a production app:
+In NocoBase CLI, the recommended production reverse-proxy entrypoints are:
 
-- `nb env proxy nginx`
-- `nb env proxy caddy`
+- `nb proxy nginx`
+- `nb proxy caddy`
 
-As long as your app has already been saved as a CLI env and the env type is `local` or `docker`, letting the CLI generate the config is usually enough. That way, the CLI keeps tricky details such as WebSocket handling, subpaths, SPA fallback pages, and later updates in sync. You only need to decide whether the entry layer should keep using Nginx or move to Caddy.
+Where:
+
+- `proxy` manages the entry layer
+- `nginx` and `caddy` are the provider implementations
+- `docker` and `local` are the runtime drivers
+- `--env <name>` selects which CLI env to generate config for
+
+As long as your app has been saved as a CLI-managed env and the env is `local` or `docker`, letting the CLI generate and manage the reverse-proxy config is usually enough. That approach keeps WebSocket handling, subpaths, SPA fallback pages, and later updates aligned in one place.
 
-If your app is not managed by the CLI, or if you explicitly want to handwrite the full proxy config, go straight to the handwritten-config section in the provider pages.
+If the app is not CLI-managed, or you intentionally want to maintain the entire proxy configuration by hand, move on to the handwritten-config sections in the provider-specific pages.
 
-## Check whether this path fits your setup
+## Before you start
 
-- Your app is already reachable through an internal address such as `http://127.0.0.1:13000`
-- The app has already been saved as a CLI env, and the env type is `local` or `docker`
-- The env already has `appPort` saved
+Make sure that:
 
-If the command says the env is missing `appPort`, run [`nb env update`](../../../api/cli/env/update.md) first and save it.
+- the app can already be reached internally, such as `http://127.0.0.1:13000`
+- the app has already been saved as a CLI env, and that env is `local` or `docker`
+- the env already has `appPort` saved
 
-If you later change settings such as `app-port` or `app-public-path` that affect proxy output, remember to rerun the matching proxy subcommand.
+If the command says the env is missing `appPort`, update it first with [`nb env update`](../../../api/cli/env/update.md).
 
-## Default path: let the CLI generate the config first
+If you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun the matching `generate` command.
 
-If you already know which entry provider you want to keep using, go straight to that subcommand:
+## Default workflow
+
+For Nginx:
 
 ```bash
-nb env proxy nginx --env demo --host demo.example.com
-nb env proxy caddy --env demo --host demo.example.com
+nb proxy nginx use docker
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
+nb proxy nginx start
 ```
 
-If you have already switched to the current env, you can also omit `--env`:
+For Caddy:
 
 ```bash
-nb env proxy nginx --host demo.example.com
+nb proxy caddy use local
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-Where:
+The roles are:
 
-- If you already use Nginx to manage sites, caching, access control, or certificates, start with [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
-- If you want HTTPS running quickly and do not want to maintain many TLS details yourself, start with [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
-- `--port` is the proxy entry port, not the app `appPort`
+- `use docker|local`: choose the runtime driver for the current provider
+- `generate --env <name> --host <domain>`: generate reverse-proxy config for one env
+- `start`: start the local process or Docker container for the current provider
 
-If you want the CLI to also connect the shared config to the provider main config and reload it after validation, add:
+If you update the config later, `reload` is usually the first choice. Use `restart` when you need a full restart of the entry layer.
 
-```bash
-nb env proxy nginx --env demo --host demo.example.com --install --reload
-```
+## How the command group is split
+
+Using Nginx as the example:
+
+| Command | Purpose |
+| --- | --- |
+| `nb proxy nginx use docker` | Switch the Nginx runtime to Docker |
+| `nb proxy nginx use local` | Switch the Nginx runtime to a local process |
+| `nb proxy nginx current` | Show the current runtime driver |
+| `nb proxy nginx generate --env <name> --host <domain>` | Generate Nginx config for one env |
+| `nb proxy nginx start` | Start Nginx |
+| `nb proxy nginx reload` | Reload the Nginx config |
+| `nb proxy nginx restart` | Restart Nginx |
+| `nb proxy nginx stop` | Stop Nginx |
+| `nb proxy nginx status` | Show Nginx status |
+| `nb proxy nginx info` | Show the current config, paths, and runtime details |
 
-For the full command reference, see [`nb env proxy`](../../../api/cli/env/proxy/index.md).
+Caddy uses the same action set, but with a different provider implementation.
 
-## What the CLI keeps in sync for you
+## What the CLI maintains
 
-The CLI does more than generate one proxy snippet. It also maintains provider-specific helper files. The output shape differs between the two providers:
+The CLI does more than produce one proxy fragment. It also keeps the helper files and site entry structure aligned with the provider:
 
-- Nginx keeps `app.conf`, `public/index-v1.html`, `public/index-v2.html`, the shared `nocobase.conf`, and the shared `snippets/`
-- Caddy keeps `generated.caddy`, `app.caddy`, and the shared `nocobase.caddy`
+- Nginx maintains shared `snippets`, `app.conf`, `public/index-v1.html`, and `public/index-v2.html`
+- Caddy maintains `nocobase.caddy`, `app.caddy`, `public/index-v1.html`, and `public/index-v2.html`, where `app.caddy` is the full site config for one env
 
 :::warning Note
 
-If you need to add site-level configuration, edit `app.conf` or `app.caddy`. Do not manually edit CLI-managed helper files, because they will be overwritten the next time you run the command.
+If you need to add site-level configuration, you usually edit `app.conf` for Nginx and use `app.caddy` as the base for Caddy. Do not edit the CLI-managed helper files directly. Also note that `app.caddy` is overwritten as a whole when you run `generate` again, while `nocobase.caddy` mainly serves as the provider-level entry file.
 
 :::
 
@@ -71,30 +96,24 @@ If you need to add site-level configuration, edit `app.conf` or `app.caddy`. Do
 
 | I want to... | Go here |
 | --- | --- |
-| Keep using Nginx to manage sites, certificates, caching, or access control | [Nginx](./nginx.md) |
-| Get HTTPS running quickly and maintain fewer certificate and TLS details | [Caddy](./caddy.md) |
-| Review the command tree and choose a provider first | [`nb env proxy`](../../../api/cli/env/proxy/index.md) |
-| See the Nginx subcommand options, output files, and examples first | [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md) |
-| See the Caddy subcommand options, output files, and examples first | [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md) |
-| Adjust env settings that may affect proxy output, such as `app-port` or `app-public-path` | [`nb env update`](../../../api/cli/env/update.md) |
-| Install the app as a CLI-managed env first | [Install with CLI (Recommended)](../../installation/cli.md) |
+| Keep using Nginx for sites, certificates, caching, or access control | [Nginx](./nginx.md) |
+| Get HTTPS running quickly with fewer TLS details to maintain | [Caddy](./caddy.md) |
+| Adjust env settings that may affect proxy behavior, such as `app-port` or `app-public-path` | [`nb env update`](../../../api/cli/env/update.md) |
+| Install the app as a CLI-managed env first | [Install with the CLI](../../installation/cli.md) |
 
-## When the CLI-generated path is not the best fit
+## When the CLI path is not the right fit
 
-These cases are usually better served by the handwritten-config section in the provider pages:
+In these cases, the handwritten-config sections in the provider-specific pages are usually a better fit:
 
-- Your app is not managed by the CLI
-- The env only has a remote API connection, or it is an SSH env
-- You explicitly want to maintain the full Nginx config or full `Caddyfile` yourself
+- the app is not CLI-managed
+- the env is only a remote API connection or an SSH env
+- you intentionally want to maintain the entire Nginx config or `Caddyfile` yourself
 
-As long as the app has already been saved as a CLI env and the current machine can reach its runtime, the default recommendation is still to start with these commands. It makes later domain changes, site-level adjustments, and regeneration much easier to manage.
+As long as the app has been saved as a CLI env and its runtime is reachable from the current machine, using this command group is still the recommended default. It is usually much easier to maintain later when you need to change the domain, add site-level config, switch drivers, or regenerate the entry files.
 
 ## Related links
 
-- [`nb env proxy`](../../../api/cli/env/proxy/index.md)
-- [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
-- [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
 - [Nginx](./nginx.md)
 - [Caddy](./caddy.md)
-- [App Environment Variables](../../installation/env.md)
-- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Environment variables](../../installation/env.md)
+- [Install with the CLI](../../installation/cli.md)