Docs: document serving the kagent UI under a sub-path for 1.x

[Rachael-Graham]

kagent#2904 added ui.basePath, which serves the UI under a prefix such as /ui behind a reverse proxy. It shipped in v1.0.0-alpha3 as the tag commit 375fe73a. The 1.x doc set covers reverse proxies nowhere, so this is new writing rather than a correction.

What the content covers

Installing kagent so the UI answers under a prefix, and what that prefix reaches beyond the UI's own routes.

The spine is that one value moves every root-relative URL the UI emits. ui.basePath sets the <base href>, the router basename, and the root-relative API, SSO, userinfo and share-link URLs together. A reader who expects to adjust publicBackendUrl by hand as well should learn that the base path already covers it.

The configuration surface

ui.basePath in helm/kagent/values.yaml, empty by default. Leaving it unset leaves the UI exactly as it is today, so the value is purely additive for an existing installation.

Both proxy shapes work: a proxy that strips the prefix before forwarding to kagent-ui:8080, and one that forwards /ui/... unchanged. nginx drops the prefix itself in the second case.

Two validations fail the Helm render rather than producing a broken UI, both in helm/kagent/templates/ui-deployment.yaml:

Condition	Message
Not a path like /ui, or containing a . or .. segment	ui.basePath must be a path like /ui
Starting with a path nginx serves	ui.basePath cannot start with a path nginx serves, such as /api or /assets

The reserved set is larger than the message suggests: api, a2a, assets, health, env-config.js, index.html, and mockServiceWorker.js. Document the full set rather than repeating the two the message names.

oauth2-proxy takes a second change. Set OIDC_REDIRECT_URL under the base path, then restart oauth2-proxy. The chart's sign-in HTML redirects to {basePath}/login, and the oauth2-proxy checksum deliberately renders without ui, so a base path change alone does not roll that pod. The restart is therefore a manual step and belongs in the instructions rather than in a closing note.

Where the content goes

Open question, and worth deciding before writing. setup/installation.md is where a reader chooses install values, but it carries no reverse proxy material for this to join, and the oauth2-proxy interaction pulls toward wherever SSO is documented. A section on the installation page is the smaller change; a page of its own is the better home if proxy material is going to grow.

What to check before starting

This needs a proxy in front of a cluster, in both shapes. The value exists to control behavior at a boundary the chart does not own.

1. Install with --set ui.basePath=/ui behind a proxy that strips the prefix. Open /ui/, go to Agents, and reload. The page must stay on /ui/agents, and API calls must go to /ui/api/....
2. Repeat behind a proxy that forwards /ui/... unchanged.
3. Install with --set ui.basePath=/api and record the rejection exactly as Helm prints it.
4. Install with the value unset and confirm the UI is unchanged at /.
5. Exercise SSO with oauth2-proxy enabled, including the OIDC_REDIRECT_URL change and the restart.

Done when

• The value, its default, and its no-op-when-unset behavior are stated.
• Both proxy shapes are covered, with a working example of at least one.
• Both rejections are documented with their messages, and the reserved set is complete.
• The oauth2-proxy steps include the restart and say why it is needed.
• A reader learns that publicBackendUrl and the other root-relative URLs inherit the prefix.
• Every command on the page was run against a cluster behind a real proxy.