Release v0.17.1

docs/docs.json

@@ -370,6 +370,7 @@
             "group": "Release Notes",
             "pages": [
               "releases/index",
+              "releases/v0.17.1",
               "releases/v0.17.0",
               "releases/v0.16.1",
               "releases/v0.16.0",
@@ -414,7 +415,7 @@
   "navbar": {
     "links": [
       {
-        "label": "v0.17.0 \u00b7 Lemonade 10.0.0",
+        "label": "v0.17.1 \u00b7 Lemonade 10.0.0",
         "href": "https://github.com/amd/gaia/releases"
       },
       {

docs/guides/agent-ui.mdx

@@ -6,6 +6,10 @@ icon: "desktop"
 
 GAIA Agent UI is a desktop interface for running AI agents **100% locally** on your AMD hardware. Use agents to analyze documents, generate code, answer questions, and accomplish tasks on your PC — all without sending data to the cloud.
 
+<Info>
+  This guide assumes you have completed the [Quickstart](/quickstart) and have GAIA installed.
+</Info>
+
 <Warning>
   **Tested Configuration:** The Agent UI has been tested exclusively on **AMD Ryzen AI MAX+ 395** processors running the **Qwen3.5-35B-A3B-GGUF** model via Lemonade Server. Other hardware or model combinations may work but are not officially verified.
 
@@ -99,6 +103,14 @@ Choose one of the two install paths:
 
     The Agent UI starts on [http://localhost:4200](http://localhost:4200). Open this URL in your browser.
 
+    <Note>
+      **Source/dev installs:** The frontend is built during `gaia init`. If you see a JSON response instead of the UI, run `gaia init` or manually build (from the repo root):
+
+      ```bash
+      cd src/gaia/apps/webui && npm install && npm run build
+      ```
+    </Note>
+
     **Options:**
 
     | Flag | Description |
@@ -166,17 +178,11 @@ See the [Agent UI MCP Server guide](/guides/mcp/agent-ui) for setup instructions
 
 <AccordionGroup>
   <Accordion title="Lemonade Server not running">
-    ```bash
-    lemonade-server serve
-    ```
-
-    If not installed, run `gaia init --profile minimal` or follow the [Setup Guide](/setup).
+    Start Lemonade with `lemonade-server serve`. If Lemonade is not installed, follow the initialization steps in the [Quickstart](/quickstart#cli-install).
   </Accordion>
 
   <Accordion title="No model loaded">
-    ```bash
-    gaia download --agent chat
-    ```
+    Download models with `gaia init --profile chat`. See the [Quickstart](/quickstart#cli-install) for details.
   </Accordion>
 
   <Accordion title="Port 4200 already in use">
@@ -198,6 +204,22 @@ See the [Agent UI MCP Server guide](/guides/mcp/agent-ui) for setup instructions
     - Keep file size under 100MB
     - For PDF image extraction, download the VLM model: `gaia download --agent chat`
   </Accordion>
+
+  <Accordion title="Frontend shows JSON instead of the UI">
+    The Agent UI frontend has not been built.
+
+    **npm install (`gaia-ui`):** This is handled automatically — `gaia-ui` tells the Python server where to find the pre-built frontend. If you still see this error, try reinstalling: `npm install -g @amd-gaia/agent-ui@latest` Then restart with `gaia-ui`.
+
+    **Source/dev installs (git clone):** Run `gaia init` to build it automatically, or manually (from the repo root):
+
+    ```bash
+    cd src/gaia/apps/webui && npm install && npm run build
+    ```
+
+    Then restart `gaia chat --ui`.
+
+    **pip/PyPI installs (without gaia-ui):** Use the [npm install path](#install-and-launch) — the pip package does not include frontend source files.
+  </Accordion>
 </AccordionGroup>
 
 ---

docs/quickstart.mdx

@@ -4,6 +4,10 @@ description: "Run AI agents locally in minutes, or build your first custom agent
 icon: "rocket"
 ---
 
+<Info>
+  This guide has two paths: **Agent UI** (npm, handles everything automatically) and **CLI / Manual Install** (requires [Setup](/setup) prerequisites first). Pick the one that fits your workflow.
+</Info>
+
 ## Agent UI (Fastest)
 
 Run AI agents **100% locally** on your AMD hardware — analyze documents, generate code, answer questions, and accomplish tasks on your PC without sending data to the cloud.

docs/releases/v0.17.1.mdx

@@ -0,0 +1,83 @@
+---
+title: "v0.17.1"
+description: "Agent UI works out of the box — automatic frontend build on gaia init, no manual npm steps"
+---
+
+# GAIA v0.17.1 Release Notes
+
+Agent UI now works from the moment you finish `gaia init` — no manual frontend build steps, no hunting for the right `npm` command. This patch release makes the first-install experience reliable and cleans up how you point to a custom frontend dist directory.
+
+```bash
+npm install -g @amd-gaia/agent-ui
+gaia-ui
+```
+
+**Why upgrade:**
+- **Agent UI works immediately after `gaia init`** — The frontend build now runs automatically during initialization on dev/source installs, so `gaia chat --ui` is ready to go without any extra steps
+- **Cleaner configuration with `--ui-dist`** — A new CLI flag replaces the opaque `GAIA_WEBUI_DIST` environment variable, making it obvious how to point to a custom frontend dist directory
+- **More reliable publishing pipeline** — The `@amd-gaia/agent-ui` npm package now publishes via OIDC trusted publishing, eliminating NPM token rotation issues that could delay releases
+
+Get started with the [Agent UI guide](/guides/agent-ui).
+
+---
+
+## What's New
+
+### Agent UI First-Install Reliability
+
+Previously, after running `gaia init` on a dev or source install, launching `gaia chat --ui` would fail because the React frontend hadn't been built yet. Users had to manually run `cd src/gaia/apps/webui && npm install && npm run build` — a step easy to miss and not clearly documented (commit f89810a3).
+
+**What you can do:**
+- Run `gaia init` once and immediately launch `gaia chat --ui` — the frontend is built automatically
+- Skip the manual build step entirely on dev/source installs
+
+**Under the hood:**
+- Extracted `_ensure_webui_built()` into a shared `gaia/ui/build.py` module used by both `gaia init` and `gaia chat --ui`
+- `gaia chat --ui` retains its staleness check and auto-rebuild as a safety net
+- Added unit tests for all new build code paths
+- Fixed Agent UI docs to clarify the Setup → Quickstart → Agent UI prerequisite chain
+
+---
+
+### `--ui-dist` Configuration Flag
+
+The `GAIA_WEBUI_DIST` environment variable for pointing to a custom frontend dist directory has been replaced with a `--ui-dist` CLI argument (commits f3af9b29, 1fa20969). This follows GAIA's CLI-first configuration pattern and makes the option discoverable via `--help`.
+
+**What you can do:**
+- `gaia chat --ui --ui-dist /path/to/dist` — point to a custom frontend build
+- `gaia-ui` npm launcher passes this automatically — no manual env var setup needed
+
+**Under the hood:**
+- `--ui-dist` accepted by both `gaia chat --ui` and the UI server directly
+- Code review advisory items A1–A5 addressed (commit b6114a42)
+
+---
+
+## Infrastructure
+
+- **OIDC trusted publishing** — `@amd-gaia/agent-ui` npm package now publishes via OIDC, removing the NPM_TOKEN secret requirement and making the publishing pipeline more reliable (PRs #638, #639)
+- **Merge queue fix** — Resolved phantom failures in the merge-queue-notify CI workflow (PR #640)
+
+---
+
+## Upgrade
+
+```bash
+npm install -g @amd-gaia/agent-ui@latest
+```
+
+---
+
+## Full Changelog
+
+**7 commits** since v0.17.0:
+
+- `1fa20969` - fix: replace GAIA_WEBUI_DIST env var with --ui-dist CLI argument
+- `b6114a42` - fix: address code review advisory items A1-A5
+- `f3af9b29` - fix: pass GAIA_WEBUI_DIST env var from gaia-ui to Python server
+- `f89810a3` - fix: build Agent UI frontend during gaia init and fix doc prerequisites
+- `334b011c` - fix: remove registry-url to enable OIDC trusted publishing (#639)
+- `776dc34a` - fix: resolve merge-queue-notify phantom failures (#640)
+- `83a4db1b` - fix: switch npm publish to OIDC trusted publishing (#638)
+
+Full Changelog: [v0.17.0...v0.17.1](https://github.com/amd/gaia/compare/v0.17.0...v0.17.1)

src/gaia/apps/webui/bin/gaia-ui.mjs

@@ -369,9 +369,8 @@ function openBrowser(url) {
 function startBackend(gaiaBin, port) {
   console.log(`Starting GAIA backend on port ${port}...`);
 
-  const child = spawn(gaiaBin, ["chat", "--ui", "--ui-port", String(port)], {
+  const child = spawn(gaiaBin, ["chat", "--ui", "--ui-port", String(port), "--ui-dist", join(ROOT_DIR, "dist")], {
     stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env },
     detached: false,
   });
 

src/gaia/apps/webui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.17.1-rc.1",
+  "version": "0.17.1",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Privacy-first agentic AI interface with document Q&A - runs 100% locally on AMD Ryzen AI",

src/gaia/cli.py

@@ -685,99 +685,16 @@ def run_cli(action, **kwargs):
 
 
 def _ensure_webui_built(log=None):
-    """Rebuild the Agent UI frontend if source files are newer than dist.
+    """Rebuild the Agent UI frontend if source files are newer than dist."""
+    from gaia.ui.build import ensure_webui_built
 
-    Only runs in dev mode (editable install) where the webui src/ directory
-    exists.  Silently skips in installed-package mode or when node/npm are
-    not available.
-    """
-    if log is None:
-        log = get_logger(__name__)
-
-    webui_dir = Path(__file__).resolve().parent / "apps" / "webui"
-    src_dir = webui_dir / "src"
-    dist_index = webui_dir / "dist" / "index.html"
-
-    # Gate 1 — dev mode only (src/ absent in pip-installed package)
-    if not src_dir.is_dir():
-        return
-
-    # Gate 2 — staleness check
-    newest_src = 0.0
-    for pattern in ("*.ts", "*.tsx", "*.css", "*.html"):
-        for path in src_dir.rglob(pattern):
-            mtime = path.stat().st_mtime
-            if mtime > newest_src:
-                newest_src = mtime
-    for root_file in ("index.html", "vite.config.ts", "tsconfig.json"):
-        p = webui_dir / root_file
-        if p.exists():
-            newest_src = max(newest_src, p.stat().st_mtime)
-
-    if dist_index.exists() and newest_src <= dist_index.stat().st_mtime:
-        log.debug("Agent UI frontend is up to date")
-        return
-
-    if dist_index.exists():
-        log.info("Agent UI frontend source is newer than built output")
-    else:
-        log.info("Agent UI frontend has not been built yet")
-
-    # Gate 3 — node/npm availability
-    if not shutil.which("node"):
-        print("Warning: Node.js not found. Cannot auto-rebuild Agent UI frontend.")
-        print("  The UI may be stale. Install Node.js from https://nodejs.org/")
-        return
-    if not shutil.which("npm"):
-        print("Warning: npm not found. Cannot auto-rebuild Agent UI frontend.")
-        return
-
-    # On Windows, npm is a .cmd batch file requiring shell execution
-    _shell = sys.platform == "win32"
-
-    # Step 1 — npm install (only if node_modules/ missing)
-    if not (webui_dir / "node_modules").is_dir():
-        print("Installing Agent UI frontend dependencies...")
-        try:
-            subprocess.run(
-                ["npm", "install"],
-                cwd=str(webui_dir),
-                check=True,
-                capture_output=True,
-                text=True,
-                shell=_shell,
-            )
-        except subprocess.CalledProcessError as e:
-            log.error("npm install failed: %s", e.stderr)
-            print(f"Warning: npm install failed: {e.stderr}")
-            print("  Continuing with existing dist/ (may be stale).")
-            return
-        except FileNotFoundError:
-            print("Warning: npm not found. Skipping frontend rebuild.")
-            return
-
-    # Step 2 — npm run build (stream output so user sees progress)
-    print("Building Agent UI frontend...", flush=True)
-    try:
-        subprocess.run(
-            ["npm", "run", "build"],
-            cwd=str(webui_dir),
-            check=True,
-            shell=_shell,
-        )
-        print("Agent UI frontend built successfully.")
-    except subprocess.CalledProcessError as e:
-        log.error("Frontend build failed (exit code %d)", e.returncode)
-        print(f"Warning: Frontend build failed (exit code {e.returncode}).")
-        if dist_index.exists():
-            print("  Continuing with existing (possibly stale) build.")
-        else:
-            print("  No existing build found. The UI will show a build hint.")
-    except FileNotFoundError:
-        print("Warning: npm not found. Skipping frontend rebuild.")
+    ensure_webui_built(
+        log_fn=log.info if log else print,
+        warn_fn=log.warning if log else print,
+    )
 
 
-def _launch_agent_ui(port=4200, base_url=None, log=None, debug=False):
+def _launch_agent_ui(port=4200, base_url=None, log=None, debug=False, webui_dist=None):
     """Launch the Agent UI server (FastAPI + uvicorn).
 
     Reused by top-level --ui, gaia chat --ui, and the interactive menu.
@@ -811,7 +728,7 @@ def _launch_agent_ui(port=4200, base_url=None, log=None, debug=False):
 
         import uvicorn
 
-        app = create_app()
+        app = create_app(webui_dist=webui_dist)
         uvicorn.run(
             app,
             host="127.0.0.1",
@@ -967,6 +884,11 @@ def main():
         default=4200,
         help="Port for the Agent UI server (default: 4200, used with --ui)",
     )
+    parser.add_argument(
+        "--ui-dist",
+        default=None,
+        help="Path to pre-built Agent UI frontend dist directory (used with --ui)",
+    )
     parser.add_argument(
         "--cli",
         action="store_true",
@@ -1139,6 +1061,11 @@ def main():
         default=4200,
         help="Port for the Agent UI server (default: 4200)",
     )
+    chat_parser.add_argument(
+        "--ui-dist",
+        default=None,
+        help="Path to pre-built Agent UI frontend dist directory (used with --ui)",
+    )
     talk_parser = subparsers.add_parser(
         "talk", help="Start voice conversation with Gaia", parents=[parent_parser]
     )
@@ -2710,6 +2637,7 @@ def main():
                 base_url=getattr(args, "base_url", None),
                 log=log,
                 debug=getattr(args, "debug", False),
+                webui_dist=getattr(args, "ui_dist", None),
             )
             return
 
@@ -2724,6 +2652,7 @@ def main():
             base_url=getattr(args, "base_url", None),
             log=log,
             debug=getattr(args, "debug", False),
+            webui_dist=getattr(args, "ui_dist", None),
         )
         return
 
@@ -2743,6 +2672,7 @@ def main():
             base_url=getattr(args, "base_url", None),
             log=log,
             debug=getattr(args, "debug", False),
+            webui_dist=getattr(args, "ui_dist", None),
         )
         return