create-lykomi-app 0.9.21 → 0.10.0

package/template/README.md

@@ -1,12 +1,14 @@
 # __PROJECT_NAME__
 
-Foundry UI starter: a chat-first React app with a Microsoft Agent Framework service exposed through AG-UI.
+LYKOMI UI starter: a React app with a Home composer, a contextual Guide page,
+and a Microsoft Agent Framework service exposed through AG-UI.
 
 ## Quick Start
 
 ```bash
 pnpm install
 cp agent/.env.example agent/.env
+# Set your Foundry project endpoint and model deployment in agent/.env.
 az login
 pnpm dev
 ```
@@ -25,14 +27,14 @@ Edit `agent/.env`:
 
 ```bash
 FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
-FOUNDRY_MODEL=gpt-5.4
+FOUNDRY_MODEL=<model-deployment-name>
 ```
 
 `FoundryChatClient` reads the Microsoft Agent Framework environment variables directly. The starter passes `DefaultAzureCredential`, so local development works with `az login`. In Azure, use managed identity or the standard service principal environment variables.
 
 ## Try It
 
-The first screen is the chat. Try:
+Home opens with the chat composer and three clickable prompts. The Guide route shows how a page sits beside the same persistent conversation, with real workbench tabs and resizable panels. Try:
 
 - `Say hello world using the hello_world tool`
 - `Check the weather in Seattle`
@@ -40,16 +42,18 @@ The first screen is the chat. Try:
 
 The bundled tools live in `agent/app/tools.py`.
 
+The starter registers Guide navigation, page context, and an “About this starter” item in the lower interface menu through `src/starter-module.ts`. Open **Working draft** and **Architecture**, edit the draft, then select **Panels**. Pin, reorder and resize windows; switch back to **Tabs** or visit Home and return. The draft stays in memory until you close it or reload. Closing an edited draft asks before discarding it. `src/pages/guide-windows.ts` owns the app data; `WindowWorkbench` and `createWindowStore` from `@lykomi/web-ui` provide the shared window behaviour. The active window context, including the draft text, accompanies an AG-UI turn. Connect your own storage service before treating the draft as saved. Local demo auth has no user identity, so that control is an interface menu; after you wire real auth, the same menu shows the signed-in user and sign-out action.
+
 ## Coding With AI Agents
 
 This app ships `AGENTS.md` (+ a `CLAUDE.md` shim) for coding agents. Claude
-Code users can also install the Foundry UI plugin — grounding for the
+Code users can also install the LYKOMI UI plugin — grounding for the
 fast-moving assistant-ui / AG-UI / Agent Framework stack plus a ChatModule
 authoring skill:
 
 ```
 /plugin marketplace add lykomi/ui
-/plugin install foundry-ui@foundry-ui
+/plugin install lykomi-ui@lykomi-ui
 ```
 
 ## Update Modes
@@ -58,43 +62,26 @@ You can use this starter in two modes:
 
 | Mode           | How                                                                    | Best for                                | Updates                                                                                                                                     |
 | -------------- | ---------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Package-backed | Keep `@iloveagents/foundry-*` dependencies in `package.json`           | Apps that want central Foundry UI fixes | Run `pnpm update @iloveagents/foundry-web-ui @iloveagents/foundry-web-shell @iloveagents/foundry-web-primitives @iloveagents/foundry-agent` |
+| Package-backed | Keep `@lykomi/*` dependencies in `package.json`           | Apps that want central LYKOMI UI fixes | Run `pnpm update @lykomi/web-ui @lykomi/web-shell @lykomi/web-primitives @lykomi/agent` |
 | Full copy      | Copy this repo or turn the generated app into your own GitHub template | Apps that need deep customization       | You own the code and manually merge upstream ideas                                                                                          |
 
 Template changes such as new files or folder structure are not applied automatically to an existing app. Package updates improve the shared UI, shell, and AG-UI transport without replacing your local `agent/` or `src/` files.
 
 ## Theme The App
 
-App name, browser title, logos, colors, radius, and fonts are configured through the `theme` layers in `src/main.tsx`.
+The starter uses LYKOMI's neutral and deep-petrol palette, light and dark V2 favicons, and a locally bundled, OFL-licensed Manrope font. Change the app name, browser title, colors, radius, and fonts in `src/theme.ts`; add logo assets under `public/` and reference them in the theme's `branding` entry.
 
 ```ts
-bootstrapShell({
-  pages: customerPages,
-  authProvider: localDemoAuth,
-  agentFetch: fetch,
-  theme: [
-    {
-      id: "app-branding",
-      definition: {
-        branding: {
-          appName: "Foundry UI",
-          appTitle: "Foundry UI",
-          logoUrl: "/logo.svg",
-          darkLogoUrl: "/logo-dark.svg",
-        },
-        light: {
-          primary: "oklch(0.54 0.21 282)",
-        },
-        radius: {
-          radius: "0.5rem",
-        },
-      },
-    },
-  ],
-});
+export const starterTheme: ThemeLayer = {
+  id: "my-app",
+  definition: {
+    light: { primary: "#3F666B" },
+    branding: { appName: "My app", appTitle: "My app" },
+  },
+};
 ```
 
-Keep `@import "@iloveagents/foundry-web-ui/styles.css";` in `src/index.css`; it exposes the package theme tokens to Tailwind.
+Keep `@import "@lykomi/web-ui/styles.css";` in `src/index.css`; it exposes the package theme tokens to Tailwind.
 
 ## Talk To It
 
@@ -103,7 +90,7 @@ variable and a microphone appears in the composer:
 
 ```bash
 # .env
-VITE_VOICE_PROXY_URL=ws://localhost:8080/ws?model=gpt-realtime
+VITE_VOICE_PROXY_URL=ws://localhost:8080/ws?model=your-voice-deployment
 ```
 
 Leave it unset and nothing is registered — no microphone, no cost, the app is
@@ -116,12 +103,9 @@ docker run -p 8080:8080 \
   -e FOUNDRY_RESOURCE_NAME=your-foundry-resource \
   -e FOUNDRY_API_KEY="…" \
   -e ALLOWED_ORIGINS="http://localhost:8010" \
-  ghcr.io/iloveagents/foundry-voice-live-proxy:latest
+  ghcr.io/iloveagents/foundry-voice-live-proxy:0.7.0
 ```
 
-> The default model (`gpt-realtime`) is available in **East US 2** and
-> **Sweden Central**.
-
 The default mode is **relay**: Voice Live transcribes what you say and speaks
 the answer, but *your* agent still answers it. A spoken turn is an ordinary
 turn — same tools, same retrieval, same history — so nothing about your agent
@@ -134,7 +118,7 @@ answer directly instead: much faster, but it only knows what your client-side
 tools tell it. On laptop speakers add `halfDuplex: true` so the assistant does
 not hear itself.
 
-Full options: [`@iloveagents/foundry-web-voice`](https://www.npmjs.com/package/@iloveagents/foundry-web-voice).
+Full options: [`@lykomi/web-voice`](https://www.npmjs.com/package/@lykomi/web-voice).
 
 ## Add A Tool
 
@@ -175,15 +159,22 @@ Agent Framework connects the MCP server when the agent runs. The AG-UI endpoint
 ```text
 agent/                  FastAPI + Microsoft Agent Framework AG-UI endpoint
 agent/app/tools.py      Add agent tools here
-src/main.tsx            Foundry UI shell bootstrap
-src/pages/chat-page.tsx Chat screen and quick starts
-src/index.css           Tailwind v4 + Foundry UI theme resource and package dist scanning
+src/main.tsx            LYKOMI UI shell bootstrap
+src/theme.ts             App colors, typography, and branding
+src/pages/starter-prompts.tsx  Home quick starts
+src/pages/guide-page.tsx       A page beside the persistent chat
+src/starter-module.ts          Guide navigation and agent context
+src/pages/chat-page.tsx  Chat route
+src/index.css           Tailwind v4 + LYKOMI UI theme resource and package dist scanning
+public/fonts/            Manrope and its OFL license
 ```
 
 ## Auth
 
 This starter uses local pass-through auth so the demo runs without an Entra app registration.
 
+The AG-UI endpoint declares `single_user=True` for this local demo. Before serving multiple users, replace that setting with an authorization scope resolver and protect the API with your chosen auth scheme. A browser-only MSAL setup does not protect the FastAPI endpoint by itself.
+
 For production MSAL auth, remove `authProvider` and `agentFetch` from `src/main.tsx`, then set:
 
 ```bash

package/template/agent/_env.example

@@ -1,6 +1,6 @@
 # Copy to agent/.env and fill these values for Microsoft Agent Framework.
 FOUNDRY_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/api/projects/your-project
-FOUNDRY_MODEL=gpt-5.4
+FOUNDRY_MODEL=your-model-deployment
 
 # DefaultAzureCredential uses `az login` locally, service principal env vars in CI,
 # and managed identity in Azure. Uncomment tenant/client values only when needed.

package/template/agent/app/agent.py

@@ -32,7 +32,7 @@ def get_agent() -> Agent:
         client=client,
         name="HelloAgent",
         instructions=(
-            "You are a concise starter assistant for a Foundry UI app. "
+            "You are a concise starter assistant for a LYKOMI UI app. "
             "Use hello_world when the user asks for hello world or a hello demo. "
             "Use get_weather when weather is requested."
         ),

package/template/agent/app/main.py

@@ -19,7 +19,7 @@ app.add_middleware(
 STATE_SCHEMA = {
     "navigation": {
         "type": "object",
-        "description": "Current app route and navigation metadata from Foundry UI.",
+        "description": "Current app route and navigation metadata from LYKOMI UI.",
         "additionalProperties": True,
     },
     "selectedItemId": {
@@ -49,6 +49,13 @@ async def health() -> dict[str, str]:
     return {"status": "ok"}
 
 
+@app.get("/api/chat/config")
+async def chat_config() -> dict[str, object]:
+    # The scaffold does not set a reasoning level or context-window limit.
+    # Leave those values unknown until the app's backend can report them.
+    return {}
+
+
 try:
     from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
 except ImportError:
@@ -59,4 +66,7 @@ add_agent_framework_fastapi_endpoint(
     get_agent(),
     path="/api/agent",
     state_schema=STATE_SCHEMA,
+    # This local starter deliberately has no user sign-in. An authenticated
+    # deployment must replace this with an authorization scope resolver.
+    single_user=True,
 )

package/template/agent/app/tools.py

@@ -10,7 +10,7 @@ def hello_world(
     name: Annotated[str, Field(description="The person, team, or event to greet.")] = "world",
 ) -> str:
     """Return a short demo greeting."""
-    return f"Hello, {name}. Your Foundry UI agent tool is wired through AG-UI."
+    return f"Hello, {name}. Your LYKOMI UI agent tool is wired through AG-UI."
 
 
 @tool(approval_mode="never_require")

package/template/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Foundry UI</title>
+    <title>LYKOMI UI</title>
   </head>
   <body>
     <div id="root"></div>

package/template/package.json

@@ -26,11 +26,12 @@
     "@assistant-ui/react": "^0.15.1",
     "@azure/msal-browser": "^5.6.3",
     "@azure/msal-react": "^5.2.1",
-    "@iloveagents/foundry-agent": "0.49.1",
-    "@iloveagents/foundry-web-primitives": "0.49.1",
-    "@iloveagents/foundry-web-shell": "0.49.1",
-    "@iloveagents/foundry-web-ui": "0.49.1",
-    "@iloveagents/foundry-web-voice": "0.1.32",
+    "@lykomi/agent": "0.50.0",
+    "@lykomi/web-primitives": "0.50.0",
+    "@lykomi/web-shell": "0.50.0",
+    "@lykomi/web-ui": "0.50.0",
+    "@lykomi/web-voice": "0.1.34",
+    "@radix-ui/react-tabs": "^1.1.22",
     "@tanstack/react-query": "^5.99.0",
     "lucide-react": "^0.553.0",
     "react": "^19.2.5",
@@ -57,5 +58,5 @@
     "typescript-eslint": "^8.58.2",
     "vite": "^7.2.2"
   },
-  "_comment_assistant_ui": "@assistant-ui/react is here only to satisfy the peer @iloveagents/foundry-web-ui declares — the app's own code never imports it. Keep the range in step with that peer (a guard test enforces it), and do NOT pin @assistant-ui/store / core / tap: those pins are what let this template fall a major line behind the packages it scaffolds, so a generated app failed to build on an API the packages had already adopted. assistant-ui's own ranges resolve a consistent graph on their own."
+  "_comment_assistant_ui": "@assistant-ui/react is here only to satisfy the peer @lykomi/web-ui declares — the app's own code never imports it. Keep the range in step with that peer (a guard test enforces it), and do NOT pin @assistant-ui/store / core / tap: those pins are what let this template fall a major line behind the packages it scaffolds, so a generated app failed to build on an API the packages had already adopted. assistant-ui's own ranges resolve a consistent graph on their own."
 }

package/template/public/favicon-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="960" viewBox="0 0 960 960" role="img" aria-label="LYKOMI abstract icon black"><title>LYKOMI abstract icon black</title><g transform="translate(165 1)"><path fill="#FFFFFF" d="M163 273 C86 322 41 387 52 465 C62 541 126 589 176 644 C232 706 233 796 154 900 C247 841 298 768 295 688 C294 611 257 558 203 509 C141 453 102 396 163 273 Z"/><path fill="#FFFFFF" d="M394 58 C357 104 292 137 246 188 C191 249 182 315 203 380 C221 446 254 482 291 525 C359 611 368 704 303 798 C383 727 422 646 405 558 C398 488 352 446 304 401 C250 352 235 307 263 251 C288 202 342 185 367 134 C382 109 390 82 394 58 Z"/><path fill="#FFFFFF" d="M392 176 C371 211 341 242 330 266 C309 319 342 339 389 351 C467 370 539 398 553 480 C581 406 537 360 483 321 C431 281 396 235 392 176 Z"/></g></svg>

package/template/public/favicon.svg

@@ -1,4 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
-  <rect width="32" height="32" rx="7" fill="#0f172a"/>
-  <path d="M9 17.4 14.2 8h8.9l-5.2 9.4h4.9L15.4 25v-7.6H9Z" fill="#34d399"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="960" viewBox="0 0 960 960" role="img" aria-label="LYKOMI abstract icon black"><title>LYKOMI abstract icon black</title><g transform="translate(165 1)"><path fill="#0B0C0E" d="M163 273 C86 322 41 387 52 465 C62 541 126 589 176 644 C232 706 233 796 154 900 C247 841 298 768 295 688 C294 611 257 558 203 509 C141 453 102 396 163 273 Z"/><path fill="#0B0C0E" d="M394 58 C357 104 292 137 246 188 C191 249 182 315 203 380 C221 446 254 482 291 525 C359 611 368 704 303 798 C383 727 422 646 405 558 C398 488 352 446 304 401 C250 352 235 307 263 251 C288 202 342 185 367 134 C382 109 390 82 394 58 Z"/><path fill="#0B0C0E" d="M392 176 C371 211 341 242 330 266 C309 319 342 339 389 351 C467 370 539 398 553 480 C581 406 537 360 483 321 C431 281 396 235 392 176 Z"/></g></svg>

package/template/public/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Manrope Project Authors (https://github.com/googlefonts/manrope)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/template/src/index.css

@@ -1,17 +1,26 @@
 @import "tailwindcss";
-@import "@iloveagents/foundry-web-ui/styles.css";
+@import "@lykomi/web-ui/styles.css";
+
+/* Manrope is bundled locally under the SIL Open Font License. */
+@font-face {
+  font-family: "Manrope";
+  src: url("/fonts/Manrope-Variable.ttf") format("truetype");
+  font-style: normal;
+  font-weight: 200 800;
+  font-display: swap;
+}
 
 /* Tailwind v4 needs explicit @source paths to scan package output
- * for utility classes. Without these, the Foundry UI components render
+ * for utility classes. Without these, the LYKOMI UI components render
  * without spacing, borders, or theme tokens. */
-@source "../node_modules/@iloveagents/foundry-web-primitives/dist";
-@source "../node_modules/@iloveagents/foundry-web-ui/dist";
-@source "../node_modules/@iloveagents/foundry-web-shell/dist";
+@source "../node_modules/@lykomi/web-primitives/dist";
+@source "../node_modules/@lykomi/web-ui/dist";
+@source "../node_modules/@lykomi/web-shell/dist";
 /* Voice is optional at RUNTIME, not at build time: the package is always a
    dependency, so its utilities must be scanned or a voice-enabled app renders
    unstyled. Scanning it costs nothing when voice is off — Tailwind emits only
    the classes something references. */
-@source "../node_modules/@iloveagents/foundry-web-voice/dist";
+@source "../node_modules/@lykomi/web-voice/dist";
 
 @plugin "tailwindcss-animate";
 

package/template/src/main.tsx

@@ -1,8 +1,12 @@
 import "./index.css";
-import { bootstrapShell } from "@iloveagents/foundry-web-shell";
-import type { AuthAdapter } from "@iloveagents/foundry-web-shell";
-import { createVoiceModule } from "@iloveagents/foundry-web-voice";
+import { bootstrapShell } from "@lykomi/web-shell";
+import type { AuthAdapter } from "@lykomi/web-shell";
+import { createVoiceModule } from "@lykomi/web-voice";
+import { registerChatSlots } from "@lykomi/web-ui";
 import { customerPages } from "@/pages/index.tsx";
+import { starterTheme } from "./theme.ts";
+import { StarterPrompts } from "./pages/starter-prompts.tsx";
+import { starterModule } from "./starter-module.ts";
 
 const localDemoAuth: AuthAdapter = {
   Provider: ({ children }) => <>{children}</>,
@@ -26,20 +30,12 @@ const voiceModules = voiceProxyUrl
   ? [createVoiceModule({ connection: { proxyUrl: voiceProxyUrl } })]
   : [];
 
+registerChatSlots({ homeStarters: StarterPrompts });
+
 bootstrapShell({
-  modules: [...voiceModules], // Add your own ChatModules here.
+  modules: [starterModule, ...voiceModules], // Add your own ChatModules here.
   pages: customerPages,
   authProvider: localDemoAuth,
   agentFetch: fetch,
-  theme: [
-    {
-      id: "app-branding",
-      definition: {
-        branding: {
-          appName: "Foundry UI",
-          appTitle: "Foundry UI",
-        },
-      },
-    },
-  ],
+  theme: [starterTheme],
 });

package/template/src/pages/chat-page.tsx

@@ -1,11 +1,5 @@
-import { ChatContent } from "@iloveagents/foundry-web-ui";
-
-const starterSuggestions = [
-  "Say hello world using the hello_world tool",
-  "Check the weather in Seattle",
-  "What tools can you use?",
-];
+import { ChatContent } from "@lykomi/web-ui";
 
 export function ChatPage() {
-  return <ChatContent starterSuggestions={starterSuggestions} />;
+  return <ChatContent />;
 }

package/template/src/pages/guide-page.tsx

@@ -0,0 +1,134 @@
+import { MessageSquare, Plus } from "lucide-react";
+import { Button, Textarea } from "@lykomi/web-primitives";
+import { WindowWorkbench } from "@lykomi/web-ui/windows";
+import {
+  useChatBubbleStore,
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from "@lykomi/web-ui";
+import { guideWindows, openGuideWindow } from "./guide-windows.ts";
+
+export function GuidePage() {
+  return (
+    <WindowWorkbench
+      controller={guideWindows}
+      toolbar={
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="sm" aria-label="Open window">
+              <Plus />
+              Open
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem onSelect={() => openGuideWindow("overview")}>Guide</DropdownMenuItem>
+            <DropdownMenuItem onSelect={() => openGuideWindow("architecture")}>
+              Architecture
+            </DropdownMenuItem>
+            <DropdownMenuItem onSelect={() => openGuideWindow("draft")}>
+              Working draft
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      }
+      empty={
+        <div className="p-8">
+          <Button onClick={() => openGuideWindow("overview")}>Open guide</Button>
+        </div>
+      }
+      getWindowContext={(tab) => ({
+        title: tab.title,
+        kind: "document",
+        windowId: tab.id,
+        content:
+          tab.text ??
+          (tab.kind === "architecture"
+            ? "Browser shell → AG-UI → FastAPI agent. Each page supplies its own context."
+            : "The starter guide explains agent configuration, page context, tabs and panels."),
+        unsavedChanges: Boolean(tab.dirty),
+      })}
+      renderWindow={(tab) => (
+        <main className="mx-auto max-w-3xl px-6 py-8 sm:px-10" aria-label={String(tab.title)}>
+          <p className="text-sm font-medium text-primary">LYKOMI UI starter</p>
+          {tab.kind === "overview" && (
+            <>
+              <h1 className="mt-2 text-3xl font-semibold tracking-tight">
+                Build an agent app around real work.
+              </h1>
+              <p className="mt-4 text-base leading-relaxed text-muted-foreground">
+                Your pages, a persistent conversation, and a shared workbench. Open a draft and the
+                architecture, then switch between tabs and panels. Your work stays in place.
+              </p>
+              <div className="mt-6 flex flex-wrap gap-2">
+                <Button onClick={() => openGuideWindow("draft")}>Open working draft</Button>
+                <Button variant="outline" onClick={() => openGuideWindow("architecture")}>
+                  Open architecture
+                </Button>
+              </div>
+              <section className="mt-8 rounded-xl border border-border bg-card p-6">
+                <h2 className="text-lg font-semibold">Connect your agent</h2>
+                <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
+                  Set <code>FOUNDRY_PROJECT_ENDPOINT</code> and <code>FOUNDRY_MODEL</code> in{" "}
+                  <code>agent/.env</code>, sign in with <code>az login</code>, then run{" "}
+                  <code>pnpm dev</code>. Replace the sample tools in <code>agent/app/tools.py</code>
+                  .
+                </p>
+              </section>
+            </>
+          )}
+          {tab.kind === "architecture" && (
+            <>
+              <h1 className="mt-2 text-2xl font-semibold">Starter architecture</h1>
+              <p className="mt-4 leading-relaxed text-muted-foreground">
+                <code>bootstrapShell</code> composes your routes, theme, modules and persistent
+                chat. The browser sends AG-UI runs to <code>/api/agent</code>, including the active
+                page and window context.
+              </p>
+              <h2 className="mt-6 text-lg font-semibold">Make the workbench yours</h2>
+              <p className="mt-2 leading-relaxed text-muted-foreground">
+                <code>createWindowStore</code> owns open windows. <code>WindowWorkbench</code>{" "}
+                renders the same content as tabs or panels. Your app supplies the content and
+                decides how to save drafts.
+              </p>
+            </>
+          )}
+          {tab.kind === "draft" && (
+            <>
+              <h1 className="mt-2 text-2xl font-semibold">Working draft</h1>
+              <p className="mt-3 text-sm text-muted-foreground">
+                Edit this draft, switch layouts, reorder its tab, or visit Home. It stays here until
+                you close it. This example keeps your work in memory for this browser session.
+              </p>
+              <label htmlFor="starter-draft" className="mt-6 block text-sm font-medium">
+                Your idea
+              </label>
+              <Textarea
+                id="starter-draft"
+                className="mt-2 min-h-48"
+                value={tab.text ?? ""}
+                onChange={(event) =>
+                  guideWindows.update(tab.id, { text: event.target.value, dirty: true })
+                }
+              />
+              <p className="mt-2 text-xs text-muted-foreground">
+                {tab.dirty
+                  ? "Unsaved changes · this demo has no storage service"
+                  : "Try editing, then switch to panels"}
+              </p>
+            </>
+          )}
+          <Button
+            variant="outline"
+            className="mt-6 gap-2"
+            onClick={() => useChatBubbleStore.getState().open()}
+          >
+            <MessageSquare className="size-4" aria-hidden />
+            Ask the agent about this page
+          </Button>
+        </main>
+      )}
+    />
+  );
+}

package/template/src/pages/guide-windows.ts

@@ -0,0 +1,32 @@
+import { createWindowStore, type WorkbenchWindow } from "@lykomi/web-ui/windows";
+
+export interface GuideWindow extends WorkbenchWindow {
+  kind: "overview" | "architecture" | "draft";
+  text?: string;
+}
+
+// App-owned data; the UI framework owns selection, pinning, ordering and layouts.
+// Keeping this store outside the route also retains drafts when visiting Home.
+export const guideWindows = createWindowStore<GuideWindow>({
+  storageKey: "starter.windows.layout",
+});
+
+export function openGuideWindow(kind: GuideWindow["kind"]) {
+  const title = { overview: "Guide", architecture: "Architecture", draft: "Working draft" }[kind];
+  guideWindows.open(
+    {
+      id: kind,
+      kind,
+      title,
+      independent: true,
+      text: kind === "draft" ? "My agent app will help people…" : undefined,
+      close: () => {
+        const tab = guideWindows.get().tabs.find((entry) => entry.id === kind);
+        if (tab?.dirty && !window.confirm("Close this draft and discard your changes?")) return;
+        guideWindows.remove(kind);
+      },
+    },
+    { mode: "new-tab" },
+  );
+}
+openGuideWindow("overview");

package/template/src/pages/index.tsx

@@ -1,5 +1,6 @@
-import type { ShellPage } from "@iloveagents/foundry-web-shell";
+import type { ShellPage } from "@lykomi/web-shell";
 import { ChatPage } from "./chat-page.tsx";
+import { GuidePage } from "./guide-page.tsx";
 
 /**
  * Customer pages list. Add your own routes here.
@@ -10,12 +11,12 @@ import { ChatPage } from "./chat-page.tsx";
  */
 export const customerPages: ShellPage[] = [
   { path: "/", element: <ChatPage /> },
+  { path: "guide", element: <GuidePage /> },
   // /chat/:aguiThreadId — clicking a Recents chat in the sidebar (or
   // reloading the URL after sending a message) navigates here. Without
   // this route react-router has no match for the location and the SPA
   // renders a blank page on the chats-as-entities resume flow.
-  // ChatPage itself is URL-agnostic; foundry-ui's
-  // ChatConversationAwareRuntime reads the thread id from the URL via
-  // `CHAT_PATH_PATTERN` in spaces-web-ui's `chat-conversation-config`.
+  // ChatPage itself is URL-agnostic. A host that persists conversations can
+  // read this route parameter and restore the matching thread.
   { path: "chat/:id", element: <ChatPage />, chatOnly: true },
 ];