create-lykomi-app 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iLoveAgents, a brand of Leitwolf GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# create-lykomi-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create a Foundry UI agent app: React chat UI, AG-UI protocol, Microsoft Agent Framework, and [Microsoft Foundry](https://learn.microsoft.com/azure/foundry/).
+
+Foundry UI is built by [iLoveAgents](https://iloveagents.ai).
+
+## Create An App
+
+```bash
+npm create lykomi-app my-agent-app
+cd my-agent-app
+cp agent/.env.example agent/.env
+az login
+pnpm dev
+```
+
+Open `http://localhost:8010`.
+
+Set these in `agent/.env`:
+
+```bash
+FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
+FOUNDRY_MODEL=gpt-5.4
+```
+
+The generated app starts:
+
+- UI: `http://localhost:8010`
+- Agent service: `http://localhost:8020`
+- AG-UI endpoint: `/api/agent`
+
+The first screen is the chat. The bundled agent can call `hello_world` and `get_weather`.
+
+## Theme The App
+
+Generated apps default to `Foundry UI` for both the shell title and browser title. Change branding, logos, colors, radius, and fonts through the `theme` layers in `src/main.tsx`.
+
+## Two Ways To Use It
+
+| Mode                   | Use when                                                         | Update story                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Package-backed app     | You want central Foundry UI fixes and a small local app surface. | Keep the generated app and update `@iloveagents/foundry-*` packages with your package manager.                          |
+| GitHub template / copy | You want to fully own and reshape the app.                       | Copy the generated app into your own template repo. You can customize everything, but you manually pull upstream ideas. |
+
+The package-backed path updates shared UI, shell, theme resources, and AG-UI transport through npm packages. It does not overwrite local files like `agent/app/tools.py`, `src/main.tsx`, or your README.
+
+## Requirements
+
+- Node.js 22+
+- pnpm
+- uv
+- Azure CLI for local `az login`
+
+## Add Tools
+
+Add Agent Framework tools in `agent/app/tools.py` and include them in `AGENT_TOOLS`.
+
+```python
+AGENT_TOOLS = [hello_world, get_weather, my_new_tool]
+```
+
+The generated `AGENTS.md` explains the local project contract for coding agents. `CLAUDE.md` imports it for Claude Code.
+
+## Options
+
+| Flag              | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `--preset <name>` | Preset to scaffold from. Default: `default`. |
+| `--no-install`    | Skip dependency install.                     |
+| `--force`         | Scaffold into a non-empty directory.         |
+
+## Presets
+
+| Preset       | What you get                                                                            |
+| ------------ | --------------------------------------------------------------------------------------- |
+| `default`    | Chat-first Foundry UI app with FastAPI Agent Framework service and hello/weather tools. |
+| `foundry-iq` | Default plus an Azure AI Search Foundry IQ knowledge base retrieval tool.               |
+
+## Packages
+
+The starter consumes the Foundry UI packages from npm:
+
+- `@iloveagents/foundry-web-shell` - browser shell and `bootstrapShell`
+- `@iloveagents/foundry-web-ui` - chat UI, AG-UI adapter, tool panels, theme resource
+- `@iloveagents/foundry-web-primitives` - shared UI primitives
+- `@iloveagents/foundry-agent` - AG-UI client transport
+
+The packages publish built ESM JavaScript and `.d.ts` declarations. The
+generated Vite app is already configured to scan their Tailwind classes from the
+package `dist` folders.
+
+Source: [`lykomi/ui`](https://github.com/lykomi/ui).
+
+## License
+
+MIT

package/dist/index.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,readdirSync as i,statSync as a,writeFileSync as o}from"node:fs";import{basename as s,dirname as c,join as l,resolve as u}from"node:path";import{spawnSync as d}from"node:child_process";import*as f from"@clack/prompts";import{readFile as p}from"node:fs/promises";import{fileURLToPath as m}from"node:url";const h=new Set([`.ts`,`.tsx`,`.js`,`.jsx`,`.mjs`,`.cjs`,`.md`,`.css`,`.html`,`.yml`,`.yaml`,`.toml`,`.env`,`.sh`,`.py`]);function g(e){let t=e.lastIndexOf(`.`);return t===-1?!0:h.has(e.slice(t))}function _(t){let{srcDir:s,dstDir:c,projectName:u,foundryPackageVersion:d,rewriteRootPackageJson:f}=t;function p(t,s,c){for(let m of i(t)){let i=l(t,m),h=a(i),_=l(s,m.startsWith(`_`)&&!m.startsWith(`__`)&&m!==`_`?`.`+m.slice(1):m);if(h.isDirectory()){n(_,{recursive:!0}),p(i,_,c+1);continue}if(f&&c===0&&m===`package.json`){let e=JSON.parse(r(i,`utf-8`));e.name=u,d&&C(e,d),o(_,JSON.stringify(e,null,2)+`
+`);continue}if(g(m)){o(_,r(i,`utf-8`).split(`__PROJECT_NAME__`).join(u));continue}e(i,_)}}p(s,c,0)}async function v(e){_({srcDir:e.sourceDir,dstDir:e.targetDir,projectName:e.projectName,foundryPackageVersion:e.foundryPackageVersion,rewriteRootPackageJson:!0})}async function y(e){_({srcDir:e.overlayDir,dstDir:e.targetDir,projectName:e.projectName,rewriteRootPackageJson:!1})}async function b(e){if(!e.extraDependencies&&!e.extraDevDependencies&&!e.extraScripts)return;let t=l(e.targetDir,`package.json`),n=JSON.parse(r(t,`utf-8`));e.extraDependencies&&(n.dependencies=x({...n.dependencies??{},...e.extraDependencies})),e.extraDevDependencies&&(n.devDependencies=x({...n.devDependencies??{},...e.extraDevDependencies})),e.extraScripts&&(n.scripts={...n.scripts??{},...e.extraScripts}),o(t,JSON.stringify(n,null,2)+`
+`)}function x(e){let t={};for(let n of Object.keys(e).sort())t[n]=e[n];return t}const S=[`@iloveagents/foundry-agent`,`@iloveagents/foundry-web-graph`,`@iloveagents/foundry-web-primitives`,`@iloveagents/foundry-web-shell`,`@iloveagents/foundry-web-ui`];function C(e,t){for(let n of[`dependencies`,`devDependencies`]){let r=e[n];if(!r||typeof r!=`object`||Array.isArray(r))continue;let i=r;for(let e of S)e in i&&(i[e]=t)}}async function w(e){if(e===`default`)return{name:e,templateDir:T()};if(e===`foundry-iq`||e===`neo4j`)return await D({name:e,presetRoot:E(e)});throw Error(`Unknown preset: ${e}`)}function T(){let e=c(m(import.meta.url)),n=e;for(let e=0;e<5;e++){let e=l(n,`template`);if(t(e))return e;let r=c(n);if(r===n)break;n=r}throw Error(`Could not locate bundled template/ relative to ${e}. Did you build the CLI? Run \`pnpm build\` in packages/create-foundry-ui-app.`)}function E(e){let n=c(m(import.meta.url)),r=n;for(let n=0;n<5;n++){let n=l(r,`presets`,e);if(t(n))return n;let i=c(r);if(i===r)break;r=i}throw Error(`Could not locate bundled presets/${e}/ relative to ${n}. Did you build the CLI? Run \`pnpm build\` in packages/create-foundry-ui-app.`)}async function D(e){let n=l(e.presetRoot,`manifest.json`);if(!t(n))throw Error(`Bundled preset '${e.name}' has no manifest.json.`);let r=JSON.parse(await p(n,`utf-8`));return O(e.name,e.presetRoot,r)}function O(e,n,r){if(r.extends&&r.extends!==`default`)throw Error(`Preset '${e}' extends '${r.extends}', but only 'default' is supported.`);let i=r.filesDir??`files`,a=l(n,i);if(!t(a))throw Error(r.filesDir===void 0?`Preset '${e}' has no '${i}/' directory at the package root (default filesDir).`:`Preset '${e}' declares filesDir='${i}' but the directory is missing in the package.`);return{name:e,templateDir:T(),overlayDir:a,extraDependencies:r.extraDependencies,extraDevDependencies:r.extraDevDependencies,extraScripts:r.extraScripts,envVars:r.envVars,postInstall:r.postInstall}}function k(e){let t={targetDir:null,preset:`default`,install:!0,force:!1,help:!1};for(let n=0;n<e.length;n++){let r=e[n];switch(r){case`-h`:case`--help`:t.help=!0;break;case`--no-install`:t.install=!1;break;case`--force`:t.force=!0;break;case`--preset`:t.preset=e[++n]??`default`;break;default:if(r.startsWith(`--`))throw Error(`Unknown flag: ${r}`);t.targetDir===null&&(t.targetDir=r)}}return t}function A(){console.log(`Usage: create-lykomi-app <target-dir> [options]
+
+Scaffold a new LYKOMI app — AG-UI protocol + Microsoft Agent Framework + Azure Foundry.
+
+Options:
+  --preset <name>    Preset to scaffold from (default: "default" — OSS shell + AG-UI agent service).
+                     Use "foundry-iq" for an Azure AI Search Foundry IQ knowledge base demo,
+                     or "neo4j" for an agent over a Neo4j graph with an interactive
+                     visualization (local database or Neo4j Aura).
+  --no-install       Skip running pnpm install in the new directory.
+  --force            Allow scaffolding into a non-empty directory.
+  -h, --help         Show this message.
+
+Example:
+  npx create-lykomi-app my-app
+  npx create-lykomi-app my-app --preset foundry-iq
+  npx create-lykomi-app my-app --preset neo4j
+`)}function j(e){if(!e||e.length===0)return;let t=e.filter(e=>e.required),n=e.filter(e=>!e.required);t.length>0&&f.log.info(`Required env vars (set before running the app):
+`+t.map(e=>`  - ${e.name}: ${e.description}`).join(`
+`)),n.length>0&&f.log.info(`Optional env vars:
+`+n.map(e=>`  - ${e.name}: ${e.description}`).join(`
+`))}function M(e){let t=l(e,`package.json`),n=JSON.parse(r(t,`utf-8`)).dependencies?.[`@iloveagents/foundry-agent`];if(!n)throw Error(`Template package.json is missing @iloveagents/foundry-agent.`);if(!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(n))throw Error(`Template @iloveagents/foundry-agent must use an exact version, got '${n}'.`);return n}async function N(){let e=k(process.argv.slice(2));if(e.help)return A(),0;let r=e.targetDir;if(!r){let e=await f.text({message:`Project directory:`,placeholder:`my-foundry-app`,validate:e=>!e||e.length===0?`Required`:void 0});if(f.isCancel(e))return f.cancel(`Cancelled.`),1;r=String(e)}let a=u(process.cwd(),r),o=t(a);if(o&&!e.force&&i(a).length>0)return f.log.error(`Target ${a} is not empty. Use --force to scaffold over it.`),1;o||n(a,{recursive:!0}),f.log.step(`Scaffolding into ${a}`),f.log.step(`Preset: ${e.preset}`);let c=await w(e.preset),l=s(a).replace(/^[^a-zA-Z]+/,``).replace(/[^a-zA-Z0-9-_]/g,`-`)||`my-app`;if(await v({sourceDir:c.templateDir,targetDir:a,projectName:l,foundryPackageVersion:M(c.templateDir)}),c.overlayDir&&await y({overlayDir:c.overlayDir,targetDir:a,projectName:l}),await b({targetDir:a,extraDependencies:c.extraDependencies,extraDevDependencies:c.extraDevDependencies,extraScripts:c.extraScripts}),f.log.success(`Files copied (preset: ${c.name}).`),e.install){let e=f.spinner();e.start(`pnpm install`);let t=d(`pnpm`,[`install`],{cwd:a,stdio:`inherit`});if(t.status!==0)return e.error(`pnpm install failed`),f.log.warn("Scaffold completed but install failed. cd into the dir and re-run `pnpm install`."),t.status??1;e.stop(`pnpm install done`)}else f.log.info(`Skipped pnpm install (--no-install).`);return j(c.envVars),f.outro(`✓ Done. Next:\n  cd ${r}\n  pnpm dev`),0}N().then(e=>process.exit(e),e=>{console.error(e instanceof Error?e.message:e),process.exit(1)});export{};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "create-lykomi-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.1",
+  "license": "MIT",
+  "description": "Scaffold a new LYKOMI app — AG-UI protocol + Microsoft Agent Framework + Azure Foundry, ready to run.",
+  "keywords": [
+    "create-app",
+    "foundry-ui",
+    "ag-ui",
+    "agent-framework",
+    "azure-foundry",
+    "scaffold"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "bin": {
+    "create-lykomi-app": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "presets",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lykomi/ui.git",
+    "directory": "packages/create-foundry-ui-app"
+  },
+  "homepage": "https://github.com/lykomi/ui/tree/main/packages/create-foundry-ui-app#readme",
+  "bugs": "https://github.com/lykomi/ui/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsdown": "^0.21.10",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/presets/foundry-iq/files/AGENTS.md

@@ -0,0 +1,72 @@
+This is a Foundry UI starter app with Foundry IQ retrieval: React chat UI, AG-UI transport, Microsoft Agent Framework, and an Azure AI Search knowledge base MCP tool.
+
+# Architecture
+
+```text
+src/main.tsx              Foundry UI shell bootstrap
+src/pages/chat-page.tsx   Chat screen and Foundry IQ starter prompts
+src/index.css             Tailwind v4 plus @iloveagents/foundry-web-ui/styles.css
+src/tools/                Foundry IQ search result tool card and ChatModule registration
+agent/app/main.py         FastAPI app, AG-UI endpoint, and request header capture
+agent/app/agent.py        FoundryChatClient + Agent configuration
+agent/app/foundry_iq.py   Foundry IQ MCP retrieval tool
+agent/app/tools.py        Local Agent Framework tools; update AGENT_TOOLS here
+```
+
+# Run
+
+```bash
+pnpm install
+cp agent/.env.example agent/.env
+az login
+pnpm dev
+```
+
+The UI runs on `http://localhost:8010`. The agent service runs on `http://localhost:8020`; Vite proxies `/api/agent` to it.
+
+# Environment
+
+Set these in `agent/.env`:
+
+```bash
+FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
+FOUNDRY_MODEL=gpt-5.4
+AZURE_AI_SEARCH_ENDPOINT=https://<search-service>.search.windows.net
+FOUNDRY_IQ_KNOWLEDGE_BASE=<knowledge-base-name>
+```
+
+`FoundryChatClient` reads its Microsoft Agent Framework env vars directly. Do not add duplicate manual env probing unless Agent Framework removes that behavior.
+
+# Foundry IQ
+
+- The Foundry IQ MCP endpoint is derived as `${AZURE_AI_SEARCH_ENDPOINT}/knowledgebases/${FOUNDRY_IQ_KNOWLEDGE_BASE}/mcp?api-version=2026-05-01-preview`.
+- The MCP tool name defaults to `knowledge_base_retrieve`.
+- The activity viewer uses the documented retrieve action with `includeActivity: true`; never synthesize activity rows.
+- `agent/app/foundry_iq.py` uses Azure AI Search AAD auth with `DefaultAzureCredential`.
+- For remote SharePoint knowledge sources, forward the signed-in user's token per request through `x-ms-query-source-authorization` or `authorization` on `/api/agent` to both MCP and retrieve calls.
+- Hosted Foundry Agent Service MCP headers are static in the current preview. Do not claim that a hosted agent can vary MCP headers per request.
+
+# Agent Tools
+
+- Add local tools in `agent/app/tools.py`.
+- Decorate local tools with `@tool(approval_mode="never_require")` unless you intentionally add an approval flow.
+- Add new local tools to `AGENT_TOOLS`; otherwise the agent cannot call them.
+- Keep the Foundry IQ tool in `agent/app/foundry_iq.py` unless you are changing retrieval behavior.
+
+# UI
+
+- Keep the starter chat-first. Do not add landing pages, marketing heroes, or domain-specific clutter.
+- Configure quick starts in `src/pages/chat-page.tsx`.
+- Keep the `foundry_iq_search` tool card and activity viewer in `src/tools/search-results-tool-ui.tsx`. If the tool output shape changes, normalize it there instead of leaking Foundry IQ-specific parsing into the shared package.
+- Configure app name, browser title, logos, colors, radius, and fonts through `theme` layers in `src/main.tsx`.
+- Keep `@source "../node_modules/@iloveagents/.../dist"` entries in `src/index.css`; Tailwind v4 needs them to scan package component classes.
+- Keep `@import "@iloveagents/foundry-web-ui/styles.css";`; it provides the Foundry UI theme tokens.
+
+# Checks
+
+```bash
+pnpm typecheck
+pnpm build
+```
+
+Use browser verification for layout or chat-flow changes.

package/presets/foundry-iq/files/README.md

@@ -0,0 +1,145 @@
+# __PROJECT_NAME__
+
+Foundry UI starter with a Microsoft Agent Framework service, AG-UI chat, and a Foundry IQ knowledge base tool.
+
+## Quick Start
+
+```bash
+pnpm install
+cp agent/.env.example agent/.env
+az login
+pnpm dev
+```
+
+Open `http://localhost:8010`.
+
+`pnpm dev` starts:
+
+- UI: `http://localhost:8010`
+- Agent service: `http://localhost:8020`
+- AG-UI endpoint: `/api/agent` proxied to the agent service
+
+## Configure Foundry
+
+Edit `agent/.env`:
+
+```bash
+FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
+FOUNDRY_MODEL=gpt-5.4
+```
+
+`FoundryChatClient` reads the Microsoft Agent Framework environment variables directly. The starter passes `DefaultAzureCredential`, so local development works with `az login`.
+
+## Configure Foundry IQ
+
+Set the Azure AI Search endpoint and knowledge base name:
+
+```bash
+AZURE_AI_SEARCH_ENDPOINT=https://<search-service>.search.windows.net
+FOUNDRY_IQ_KNOWLEDGE_BASE=<knowledge-base-name>
+```
+
+The tool derives the MCP endpoint documented for Foundry IQ:
+
+```text
+${AZURE_AI_SEARCH_ENDPOINT}/knowledgebases/${FOUNDRY_IQ_KNOWLEDGE_BASE}/mcp?api-version=2026-05-01-preview
+```
+
+The MCP tool name defaults to `knowledge_base_retrieve`. Override only if your service exposes a different tool:
+
+```bash
+FOUNDRY_IQ_MCP_TOOL_NAME=knowledge_base_retrieve
+```
+
+For the activity viewer, the starter also calls the documented Azure AI Search retrieve action with `includeActivity: true`:
+
+```text
+${AZURE_AI_SEARCH_ENDPOINT}/knowledgebases/${FOUNDRY_IQ_KNOWLEDGE_BASE}/retrieve?api-version=2026-05-01-preview
+```
+
+This is real service activity data from the `activity` array. Disable the extra diagnostic call only when you want MCP-only retrieval:
+
+```bash
+FOUNDRY_IQ_INCLUDE_ACTIVITY=false
+```
+
+## Security Trimming
+
+For remote SharePoint knowledge sources, Foundry IQ requires the `x-ms-query-source-authorization` header. In this starter, `agent/app/main.py` captures the incoming request's `x-ms-query-source-authorization` or `authorization` header and `agent/app/foundry_iq.py` forwards it per request to the MCP endpoint and the retrieve action.
+
+For local development without a signed-in UI user, you can set:
+
+```bash
+FOUNDRY_IQ_QUERY_SOURCE_AUTHORIZATION=Bearer <user-token>
+```
+
+Do not use that fallback for production multi-user apps. Hosted Foundry Agent Service MCP headers are static in the current preview; for per-user security trimming, keep the per-request forwarding in your app/API layer.
+
+## Try It
+
+The first screen is the chat. Try:
+
+- `Search Foundry IQ for a knowledge base summary`
+- `What sources are available in the knowledge base?`
+- `Say hello world using the hello_world tool`
+
+The Foundry IQ tool lives in `agent/app/foundry_iq.py`; normal demo tools live in `agent/app/tools.py`.
+
+The chat renders `foundry_iq_search` with a search-results tool card and an expandable activity viewer for tuning query planning, search-source calls, token usage, timings, and result counts. The UI lives in:
+
+```text
+src/tools/search-results-tool-ui.tsx
+src/tools/foundry-iq-module.tsx
+```
+
+Use that pattern for other search/retrieval tools: create a `makeAssistantToolUI` for the tool name, normalize the tool payload in the card, then register it through a `ChatModule` in `src/main.tsx`.
+
+## Add A Tool
+
+Add a function in `agent/app/tools.py` and include it in `AGENT_TOOLS`:
+
+```python
+from typing import Annotated
+
+from agent_framework import tool
+from pydantic import Field
+
+
+@tool(approval_mode="never_require")
+def get_time(
+    city: Annotated[str, Field(description="The city to report time for.")],
+) -> str:
+    """Return a demo time response."""
+    return f"It is demo time in {city}."
+
+
+AGENT_TOOLS = [hello_world, get_weather, get_time]
+```
+
+Restart `pnpm dev` after changing Python dependencies or environment variables. Tool code itself reloads through Uvicorn.
+
+## Project Map
+
+```text
+agent/                      FastAPI + Microsoft Agent Framework AG-UI endpoint
+agent/app/foundry_iq.py     Foundry IQ MCP retrieval tool
+agent/app/tools.py          Add local agent tools here
+src/main.tsx                Foundry UI shell bootstrap
+src/pages/chat-page.tsx     Chat screen and quick starts
+src/tools/                  Custom tool cards registered through ChatModules
+src/index.css               Tailwind v4 + Foundry UI theme resource and package dist scanning
+```
+
+## Auth
+
+This starter uses local pass-through auth so the demo runs without an Entra app registration.
+
+For production MSAL auth, remove `authProvider` and `agentFetch` from `src/main.tsx`, then set:
+
+```bash
+VITE_MSAL_CLIENT_ID=<client-id>
+VITE_MSAL_AUTHORITY=https://login.microsoftonline.com/<tenant-id>
+VITE_MSAL_API_SCOPE=api://<api-app-id>/access_as_user
+```
+
+Ensure your authenticated fetch path forwards the user's bearer token to `/api/agent`.

package/presets/foundry-iq/files/agent/_env.example

@@ -0,0 +1,22 @@
+# 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 IQ MCP endpoint inputs.
+# The app derives:
+# ${AZURE_AI_SEARCH_ENDPOINT}/knowledgebases/${FOUNDRY_IQ_KNOWLEDGE_BASE}/mcp?api-version=2026-05-01-preview
+# and uses the documented retrieve action with includeActivity=true for real activity diagnostics.
+AZURE_AI_SEARCH_ENDPOINT=https://your-search.search.windows.net
+FOUNDRY_IQ_KNOWLEDGE_BASE=your-knowledge-base
+# FOUNDRY_IQ_INCLUDE_ACTIVITY=true
+# FOUNDRY_IQ_MAX_OUTPUT_DOCUMENTS=6
+
+# Optional local-dev fallback for SharePoint-backed knowledge sources.
+# Production should pass the signed-in user's bearer token per request instead.
+# FOUNDRY_IQ_QUERY_SOURCE_AUTHORIZATION=Bearer <user-token>
+
+# DefaultAzureCredential uses `az login` locally, service principal env vars in CI,
+# and managed identity in Azure. Uncomment tenant/client values only when needed.
+# AZURE_TENANT_ID=
+# AZURE_CLIENT_ID=
+# AZURE_CLIENT_SECRET=

package/presets/foundry-iq/files/agent/app/agent.py

@@ -0,0 +1,26 @@
+from functools import lru_cache
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import DefaultAzureCredential
+
+from .foundry_iq import FOUNDRY_IQ_TOOLS
+from .tools import AGENT_TOOLS
+
+
+@lru_cache(maxsize=1)
+def get_agent() -> Agent:
+    client = FoundryChatClient(credential=DefaultAzureCredential())
+
+    return Agent(
+        client=client,
+        name="FoundryIQAgent",
+        instructions=(
+            "You are a concise assistant for a Foundry UI app. "
+            "Use foundry_iq_search when the user asks about knowledge-base content, "
+            "documents, SharePoint-backed content, or retrieval-backed answers. "
+            "Use hello_world when the user asks for hello world or a hello demo. "
+            "Use get_weather when weather is requested."
+        ),
+        tools=[*AGENT_TOOLS, *FOUNDRY_IQ_TOOLS],
+    )