docs: route applications by host/urlPath in the root config

Follow-up to #595. That PR documented `host`/`urlPath` as a component-`config.yaml`
setting, which described the mechanism but put the routing in the wrong place: where an
application is served is a deployment concern, and a value checked into the application
cannot be remapped per environment (the env-config overlay is root-config-only).

Harper now treats the application's root-config entry as authoritative (HarperFast/harper
PR pending), so lead with that placement:

- `reference/http/overview.md` — mount an application from the root `harper-config.yaml`;
  a plugin's own `urlPath` positions it within the app and the mount is prefixed onto it,
  while a root-config `host` overrides one the app shipped.
- `reference/components/plugin-api.md` — scope the plugin-level options to "within the
  application" and point at the root-config mount.
- `reference/operations-api/operations.md` — document `host` on `deploy_component` and
  note that both it and `urlPath` are persisted to the root-config entry.
- 5.2 release notes — lead with the application mount.

Author: kriszyp

reference/components/plugin-api.md

@@ -42,7 +42,9 @@ General plugin configuration options:
 - `host` — `string` _(optional)_ — Virtual hostname used to route the plugin's HTTP, WebSocket, and upgrade handlers
 - `timeout` — `number` _(optional)_ — Timeout in milliseconds for plugin operations. Takes precedence over the plugin's `defaultTimeout` and the system default (30 seconds)
 
-`urlPath` and `host` are available in v5.2.0. Harper automatically passes them to handlers registered through the scoped `server` API. See [Middleware routing](../http/overview#middleware-routing) for an example and [`HttpOptions`](../http/api#httpoptions) for matching behavior.
+`urlPath` and `host` are available in v5.2.0. Harper automatically passes them to handlers registered through the scoped `server` API.
+
+These position a plugin **within** its application. Where the application itself is served is set on the application's entry in the root `harper-config.yaml`; that mount is prefixed onto each plugin's `urlPath`, and a `host` there overrides one set here. See [Middleware routing](../http/overview#middleware-routing) for the full picture and [`HttpOptions`](../http/api#httpoptions) for matching behavior.
 
 ### File Entries
 

reference/http/overview.md

@@ -30,18 +30,39 @@ Request and response objects follow the [WHATWG Fetch API](https://developer.moz
 
 <VersionBadge version="v5.2.0" />
 
-Harper can route middleware by URL prefix, virtual hostname, or both. Set `urlPath` or `host` in a component's `config.yaml` to create a routed middleware chain without writing dispatch code:
+Harper can route middleware by URL prefix, virtual hostname, or both, with no dispatch code in the application. Where an application is served is a deployment concern, so declare it on that application's entry in the root `harper-config.yaml`:
 
 ```yaml
-rest:
+# harper-config.yaml
+my-app:
   host: api.example.com
   urlPath: /v1
+```
+
+Every handler the application registers — HTTP, WebSocket, and upgrade — is then served under `api.example.com/v1`, and Harper removes `/v1` from the pathname before invoking the chain. Requests that match no routed chain use the default middleware chain.
+
+Because routing lives in the root config, the same application package can be mounted at a different hostname or path per environment without editing the application. The entry does not need a `package` — routing applies to any application in the components root, however it was deployed.
+
+You can also set it at deploy time:
+
+```bash
+harper deploy project=my-app package=@my/app host=api.example.com urlPath=/v1
+```
+
+#### Routing individual plugins
+
+A plugin's own `urlPath` sets where it sits **within** the application, and is configured in the application's `config.yaml`:
+
+```yaml
+# my-app/config.yaml
 static:
   files: 'web/**'
-  host: www.example.com
+  urlPath: assets
 ```
 
-The `rest` handler receives requests under `api.example.com/v1`; Harper removes `/v1` from the pathname before invoking the chain. The `static` handler receives requests for `www.example.com`. Unmatched requests use the default middleware chain.
+The application's mount composes with it rather than replacing it, so app-internal structure survives being relocated. With the root config above, the static files are served at `api.example.com/v1/assets/`. A plugin that configures no `urlPath` of its own is served at the mount itself (`api.example.com/v1`).
+
+An application can also set `host` per plugin, but a `host` on the root-config entry overrides it — the operator's choice of hostname wins over one the application shipped.
 
 Custom components can configure the same behavior programmatically with `server.http(listener, { host, urlPath })`. See [`HttpOptions`](./api#httpoptions) for matching priority and middleware ordering options.
 

reference/operations-api/operations.md

@@ -604,7 +604,8 @@ Deploys a component. The `package` option accepts any valid NPM reference includ
 
 Additional parameters:
 
-- `urlPath` — override the HTTP URL path the component is mounted at (e.g. `"/api/v2"`)
+- `urlPath` — the HTTP URL path the component is mounted at (e.g. `"/api/v2"`). Persisted on the component's root-config entry; see [HTTP middleware routing](/reference/v5/http/overview#middleware-routing).
+- `host` — the virtual hostname the component is served on (e.g. `"api.example.com"`). Must be a bare hostname — no scheme, port, or path. Persisted alongside `urlPath`.
 - `install_allow_scripts` — set to `true` to allow npm pre/post install scripts (disabled by default)
 - `credentials` — credentials for installing a component from a private npm registry or private git repository (see below)
 

release-notes/v5-lincoln/5.2.md

@@ -36,7 +36,9 @@ CLI Operations API commands now accept dedicated `auth_username=` and `auth_pass
 
 ### Middleware routing and ordering
 
-Components can now declare `host` and `urlPath` in `config.yaml`, or pass them to `server.http()`, `server.ws()`, and `server.upgrade()`, to create middleware chains routed by virtual hostname, URL prefix, or both. The new `name`, `before`, and `after` options provide explicit middleware ordering. See [HTTP middleware routing](/reference/v5/http/overview#middleware-routing) and [`HttpOptions`](/reference/v5/http/api#httpoptions).
+Applications can now be routed by virtual hostname, URL prefix, or both, with no dispatch code. Declare `host` and `urlPath` on the application's entry in the root `harper-config.yaml` — or pass them to `deploy_component` — and every handler the application registers is served under that hostname and path. Because the routing lives in the root config, the same application can be mounted differently per environment without editing it. A plugin's own `urlPath` still positions it within the application, and the application's mount is prefixed onto it.
+
+Components can also pass `host` and `urlPath` directly to `server.http()`, `server.ws()`, and `server.upgrade()`. The new `name`, `before`, and `after` options provide explicit middleware ordering. See [HTTP middleware routing](/reference/v5/http/overview#middleware-routing) and [`HttpOptions`](/reference/v5/http/api#httpoptions).
 
 ## Security