create-lykomi-app 0.11.1 → 0.13.0

package/README.md

@@ -34,6 +34,14 @@ Home opens with a chat composer and clickable prompts. Guide demonstrates a page
 
 The lower interface menu links to the Guide in local demo mode. Connecting a real auth provider makes it the signed-in user menu.
 
+## Explore Before Connecting Azure
+
+Run `pnpm dev:web`, then open **Showcase** at `/showcase`. Six working examples cover forms, collections, dashboards, guided processes, tabs/panels and feedback. A live inspector shows actual AG-UI context and client tools; source panels expose the example code. UI interactions work without credentials. Agent replies require your configured backend.
+
+Every preset also includes five coding skills in `.agents/skills/` and `.claude/skills/`: API grounding, ChatModules, agent-aware forms, workbenches and browser verification. No global installation is required. These teach your coding assistant how to build the app; runtime tools belong to your agent and page modules.
+
+The showcase is a lazy, removable `showcaseModule` in `src/main.tsx`. Example data is local and disposable. Use the examples as a starting point, then connect your own persistence and application tools.
+
 ## Theme The App
 
 Generated apps use LYKOMI's neutral and deep-petrol palette, light and dark V2 favicons, a locally bundled Manrope font, and `LYKOMI UI` for the shell and browser title. Edit `src/theme.ts` to change branding, colors, radius, and typography.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lykomi-app",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "license": "MIT",
   "description": "Scaffold a new LYKOMI app — AG-UI protocol + Microsoft Agent Framework + Azure Foundry, ready to run.",
   "keywords": [

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

@@ -70,3 +70,9 @@ pnpm build
 ```
 
 Use browser verification for layout or chat-flow changes.
+
+## Local skills and examples
+
+Use the repository-local skills in `.agents/skills/` or `.claude/skills/` for grounding, ChatModules, agent-aware forms, workbenches and browser verification. Their bundled form UX references describe the shared component contract. These are coding-assistant instructions, not runtime chat skills.
+
+`src/showcase/` is a removable, lazy example module. Its inspector reads actual framework state. Keep privacy opt-outs, expected-value checks and read/edit boundaries when adapting an example. Run `pnpm dev:web` to explore without an agent; real replies need the configured service.

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

@@ -143,3 +143,23 @@ 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`.
+
+## Component showcase
+
+Run `pnpm dev:web` and open `/showcase` to explore six interactive examples without Azure credentials: forms, collections, dashboards, processes, workbench windows and feedback. The live inspector reads the framework’s actual AG-UI state and available client tools. Select text in a field, filter a table, or change the active window to see the context change. Source panels contain the exact example code, ready to copy.
+
+Connect the agent service with `pnpm dev` to ask about that context or request a guarded draft edit. The inspector works offline; agent replies require your configured backend. Examples use local, disposable data. Saving a form accepts it only in this example; leaving the example resets it. The feedback example explicitly simulates outcomes.
+
+The showcase is a lazy `ChatModule` in `src/showcase/module.tsx`. Remove `showcaseModule` from the imports and `modules` list in `src/main.tsx` to remove its route and navigation; you can then delete `src/showcase/`. Your own app keeps using the same framework components.
+
+## Bundled coding skills
+
+Five repository-local skills ship in both `.agents/skills/` (Codex and compatible tools) and `.claude/skills/` (Claude Code):
+
+- `lykomi-verify-agent-apis`: verify current framework and library APIs.
+- `lykomi-author-chat-module`: compose pages, navigation and agent tools.
+- `lykomi-build-agent-forms`: build consistent read/edit forms with automatic field context and guarded edits.
+- `lykomi-build-workbench`: connect windows, tables and processes to visible context.
+- `lykomi-verify-ui`: verify real browser behavior, context and package boundaries.
+
+These guide your coding assistant; they are not runtime tools for the chat agent. They install only in this project and do not change global configuration. The optional Claude Code plugin adds documentation MCP servers; it is not required for these bundled skills. Keep project-specific adaptations in your generated app.

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

@@ -1,5 +1,7 @@
 from functools import lru_cache
 
+from .skills import ChatSkillsProvider, get_skills_source
+
 from agent_framework import Agent
 from agent_framework.foundry import FoundryChatClient
 from azure.identity import DefaultAzureCredential
@@ -13,6 +15,7 @@ def get_agent() -> Agent:
     client = FoundryChatClient(credential=DefaultAzureCredential())
 
     return Agent(
+        context_providers=[ChatSkillsProvider(get_skills_source())],
         client=client,
         name="FoundryIQAgent",
         instructions=(

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

@@ -3,6 +3,8 @@ from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 
 from .agent import get_agent
+from .skills import get_skills_source
+from agent_framework import SkillsSourceContext
 from .foundry_iq import reset_query_source_authorization, set_query_source_authorization
 
 load_dotenv()
@@ -22,10 +24,9 @@ app.add_middleware(
 async def foundry_iq_security_trimming_context(request: Request, call_next):
     # x-ms-query-source-authorization is preferred; authorization is a local-dev
     # fallback for passing the signed-in user's bearer token to security trimming.
-    query_source_authorization = (
-        request.headers.get("x-ms-query-source-authorization")
-        or request.headers.get("authorization")
-    )
+    query_source_authorization = request.headers.get(
+        "x-ms-query-source-authorization"
+    ) or request.headers.get("authorization")
     token = set_query_source_authorization(query_source_authorization)
     try:
         return await call_next(request)
@@ -66,6 +67,23 @@ async def health() -> dict[str, str]:
     return {"status": "ok"}
 
 
+@app.get("/api/chat/config")
+async def chat_config() -> dict[str, object]:
+    skills = await get_skills_source().get_skills(
+        SkillsSourceContext(agent=get_agent())
+    )
+    return {
+        "skills": [
+            {
+                "name": skill.frontmatter.name,
+                "description": skill.frontmatter.description,
+                "scope": "app",
+            }
+            for skill in skills
+        ]
+    }
+
+
 try:
     from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
 except ImportError:

package/presets/foundry-iq/files/agent/pyproject.toml

@@ -4,9 +4,9 @@ version = "0.0.0"
 description = "FastAPI + Microsoft Agent Framework service for __PROJECT_NAME__ with Foundry IQ MCP retrieval."
 requires-python = ">=3.12,<3.14"
 dependencies = [
-  "agent-framework-ag-ui>=1.0.0b260429",
-  "agent-framework-core>=1.2.2,<2",
-  "agent-framework-foundry>=1.2.2,<2",
+  "agent-framework-ag-ui>=1.1.0",
+  "agent-framework-core>=1.14.0,<2",
+  "agent-framework-foundry>=1.11.0,<2",
   "azure-identity>=1.25.1",
   "fastapi[standard]>=0.115.0",
   "httpx>=0.28.0",

package/presets/foundry-iq/files/src/main.tsx

@@ -1,4 +1,5 @@
 import "./index.css";
+import { showcaseModule } from "./showcase/module.tsx";
 import { bootstrapShell } from "@lykomi/web-shell";
 import type { AuthAdapter } from "@lykomi/web-shell";
 import { customerPages } from "@/pages/index.tsx";
@@ -9,7 +10,7 @@ const localDemoAuth: AuthAdapter = {
 };
 
 bootstrapShell({
-  modules: [foundryIqModule],
+  modules: [showcaseModule, foundryIqModule],
   pages: customerPages,
   authProvider: localDemoAuth,
   agentFetch: fetch,

package/presets/neo4j/files/AGENTS.md

@@ -88,3 +88,9 @@ The agent can also call `show_graph` with a payload to put any graph in the side
 # Where the visualization lives
 
 `@lykomi/web-graph`, an npm package. It is source-neutral: it takes the payload contract and knows nothing about Neo4j or Cypher. Its `@lykomi/web-graph/adapters/neo4j` entry point converts driver-shaped records in the browser, for apps that query a graph directly rather than through an agent.
+
+## Local skills and examples
+
+Use the repository-local skills in `.agents/skills/` or `.claude/skills/` for grounding, ChatModules, agent-aware forms, workbenches and browser verification. Their bundled form UX references describe the shared component contract. These are coding-assistant instructions, not runtime chat skills.
+
+`src/showcase/` is a removable, lazy example module. Its inspector reads actual framework state. Keep privacy opt-outs, expected-value checks and read/edit boundaries when adapting an example. Run `pnpm dev:web` to explore without an agent; real replies need the configured service.

package/presets/neo4j/files/README.md

@@ -185,3 +185,23 @@ docker-compose.yml          local Neo4j (development only)
 The visualization itself is `@lykomi/web-graph`, which knows
 nothing about Neo4j — it takes a source-neutral payload. You can point it at
 any graph data you have.
+
+## Component showcase
+
+Run `pnpm dev:web` and open `/showcase` to explore six interactive examples without Azure credentials: forms, collections, dashboards, processes, workbench windows and feedback. The live inspector reads the framework’s actual AG-UI state and available client tools. Select text in a field, filter a table, or change the active window to see the context change. Source panels contain the exact example code, ready to copy.
+
+Connect the agent service with `pnpm dev` to ask about that context or request a guarded draft edit. The inspector works offline; agent replies require your configured backend. Examples use local, disposable data. Saving a form accepts it only in this example; leaving the example resets it. The feedback example explicitly simulates outcomes.
+
+The showcase is a lazy `ChatModule` in `src/showcase/module.tsx`. Remove `showcaseModule` from the imports and `modules` list in `src/main.tsx` to remove its route and navigation; you can then delete `src/showcase/`. Your own app keeps using the same framework components.
+
+## Bundled coding skills
+
+Five repository-local skills ship in both `.agents/skills/` (Codex and compatible tools) and `.claude/skills/` (Claude Code):
+
+- `lykomi-verify-agent-apis`: verify current framework and library APIs.
+- `lykomi-author-chat-module`: compose pages, navigation and agent tools.
+- `lykomi-build-agent-forms`: build consistent read/edit forms with automatic field context and guarded edits.
+- `lykomi-build-workbench`: connect windows, tables and processes to visible context.
+- `lykomi-verify-ui`: verify real browser behavior, context and package boundaries.
+
+These guide your coding assistant; they are not runtime tools for the chat agent. They install only in this project and do not change global configuration. The optional Claude Code plugin adds documentation MCP servers; it is not required for these bundled skills. Keep project-specific adaptations in your generated app.

package/presets/neo4j/files/agent/app/agent.py

@@ -1,5 +1,7 @@
 from functools import lru_cache
 
+from .skills import ChatSkillsProvider, get_skills_source
+
 from agent_framework import Agent
 from agent_framework.foundry import FoundryChatClient
 from azure.identity import DefaultAzureCredential
@@ -13,6 +15,7 @@ def get_agent() -> Agent:
     client = FoundryChatClient(credential=DefaultAzureCredential())
 
     return Agent(
+        context_providers=[ChatSkillsProvider(get_skills_source())],
         client=client,
         name="GraphAgent",
         instructions=(

package/presets/neo4j/files/agent/app/main.py

@@ -4,6 +4,8 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from .agent import get_agent
+from .skills import get_skills_source
+from agent_framework import SkillsSourceContext
 from .graph_db import close_driver
 
 
@@ -62,6 +64,23 @@ async def health() -> dict[str, str]:
     return {"status": "ok"}
 
 
+@app.get("/api/chat/config")
+async def chat_config() -> dict[str, object]:
+    skills = await get_skills_source().get_skills(
+        SkillsSourceContext(agent=get_agent())
+    )
+    return {
+        "skills": [
+            {
+                "name": skill.frontmatter.name,
+                "description": skill.frontmatter.description,
+                "scope": "app",
+            }
+            for skill in skills
+        ]
+    }
+
+
 try:
     from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
 except ImportError:

package/presets/neo4j/files/agent/pyproject.toml

@@ -4,11 +4,11 @@ version = "0.0.0"
 description = "FastAPI + Microsoft Agent Framework graph service for __PROJECT_NAME__."
 requires-python = ">=3.12,<3.14"
 dependencies = [
-  "agent-framework-ag-ui>=1.0.0b260429",
-  "agent-framework-core>=1.2.2,<2",
+  "agent-framework-ag-ui>=1.1.0",
+  "agent-framework-core>=1.14.0,<2",
   # Also provides FoundryEmbeddingClient, used by graph_vector_search — no
   # second SDK and no second credential story for embeddings.
-  "agent-framework-foundry>=1.2.2,<2",
+  "agent-framework-foundry>=1.11.0,<2",
   "azure-identity>=1.25.1",
   "fastapi[standard]>=0.115.0",
   # Vector indexes need a 5.13+ server; any recent driver talks to one.

package/presets/neo4j/files/src/main.tsx

@@ -1,4 +1,5 @@
 import "./index.css";
+import { showcaseModule } from "./showcase/module.tsx";
 import { bootstrapShell } from "@lykomi/web-shell";
 import type { AuthAdapter } from "@lykomi/web-shell";
 import { createVoiceModule } from "@lykomi/web-voice";
@@ -25,7 +26,7 @@ const voiceModules = voiceProxyUrl
   : [];
 
 bootstrapShell({
-  modules: [...voiceModules, graphModule],
+  modules: [showcaseModule, ...voiceModules, graphModule],
   pages: customerPages,
   authProvider: localDemoAuth,
   agentFetch: fetch,

package/presets/neo4j/manifest.json

@@ -5,7 +5,7 @@
   "extends": "default",
   "filesDir": "files",
   "extraDependencies": {
-    "@lykomi/web-graph": "0.3.20"
+    "@lykomi/web-graph": "0.3.21"
   },
   "extraScripts": {
     "graph:up": "docker compose up -d",

package/template/AGENTS.md

@@ -76,3 +76,9 @@ pnpm build
 ```
 
 Use browser verification for layout or chat-flow changes.
+
+## Local skills and examples
+
+Use the repository-local skills in `.agents/skills/` or `.claude/skills/` for grounding, ChatModules, agent-aware forms, workbenches and browser verification. Their bundled form UX references describe the shared component contract. These are coding-assistant instructions, not runtime chat skills.
+
+`src/showcase/` is a removable, lazy example module. Its inspector reads actual framework state. Keep privacy opt-outs, expected-value checks and read/edit boundaries when adapting an example. Run `pnpm dev:web` to explore without an agent; real replies need the configured service.

package/template/README.md

@@ -66,10 +66,7 @@ Connect an authenticated storage service before saving remotely.
 
 ## Coding With AI Agents
 
-This app ships `AGENTS.md` (+ a `CLAUDE.md` shim) for coding agents. Claude
-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:
+This app ships `AGENTS.md`, a `CLAUDE.md` shim, and five [local coding skills](#bundled-coding-skills). No extra install is needed for the skills. Claude Code users can optionally install the LYKOMI UI plugin for documentation MCP servers and centrally updated skills:
 
 ```
 /plugin marketplace add lykomi/ui
@@ -208,3 +205,45 @@ VITE_MSAL_API_SCOPE=api://<api-app-id>/access_as_user
 - `AGENTS.md` is the local coding-agent contract.
 - `CLAUDE.md` imports `AGENTS.md` for Claude Code.
 - Images and documents (PDF/DOCX) are sent to the model as file content. Use `new FileAttachmentAdapter({ documentMode: "metadata" })` if your model cannot accept file input, and elide attachment bytes before persisting chat history.
+
+## Component showcase
+
+Run `pnpm dev:web` and open `/showcase` to explore six interactive examples without Azure credentials: forms, collections, dashboards, processes, workbench windows and feedback. The live inspector reads the framework’s actual AG-UI state and available client tools. Select text in a field, filter a table, or change the active window to see the context change. Source panels contain the exact example code, ready to copy.
+
+Connect the agent service with `pnpm dev` to ask about that context or request a guarded draft edit. The inspector works offline; agent replies require your configured backend. Examples use local, disposable data. Saving a form accepts it only in this example; leaving the example resets it. The feedback example explicitly simulates outcomes.
+
+The showcase is a lazy `ChatModule` in `src/showcase/module.tsx`. Remove `showcaseModule` from the imports and `modules` list in `src/main.tsx` to remove its route and navigation; you can then delete `src/showcase/`. Your own app keeps using the same framework components.
+
+## Bundled coding skills
+
+Five repository-local skills ship in both `.agents/skills/` (Codex and compatible tools) and `.claude/skills/` (Claude Code):
+
+- `lykomi-verify-agent-apis`: verify current framework and library APIs.
+- `lykomi-author-chat-module`: compose pages, navigation and agent tools.
+- `lykomi-build-agent-forms`: build consistent read/edit forms with automatic field context and guarded edits.
+- `lykomi-build-workbench`: connect windows, tables and processes to visible context.
+- `lykomi-verify-ui`: verify real browser behavior, context and package boundaries.
+
+These guide your coding assistant; they are not runtime tools for the chat agent. They install only in this project and do not change global configuration. The optional Claude Code plugin adds documentation MCP servers; it is not required for these bundled skills. Keep project-specific adaptations in your generated app.
+
+## Skills in the running chat
+
+Type `/` in the composer or use **+ → Use a skill**. The included `/plan-work`
+skill turns your request and current page context into a practical work plan.
+Add runtime skills as `agent/skills/<name>/SKILL.md` with `name` and `description`
+in YAML frontmatter. Restart the agent after adding or editing skills.
+
+`agent/app/skills.py` connects Agent Framework discovery with explicit slash
+selection. A selected skill is resolved and loaded before the model runs; normal
+chat can also discover skills automatically. The backend owns the catalogue and
+permissions. No script runner is configured by this starter.
+
+These runtime skills serve the app's users. The `.agents/skills/` and
+`.claude/skills/` directories instead help coding agents develop the application.
+
+Run the runtime checks without Azure credentials from `agent/`:
+`uv run python -m unittest discover -s tests -v`.
+
+The Collections showcase loads 120 local example tasks in batches and registers
+row/bulk actions once with `useDataTableActions`. The agent uses those same actions;
+Delete waits for your confirmation. All example changes stay in the browser.

package/template/_agents/skills/lykomi-author-chat-module/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: lykomi-author-chat-module
+description: Author a LYKOMI UI ChatModule — the unit of composition for bootstrapShell() apps. Use when adding a feature module to an app built on @lykomi/web-shell (new pages, tool UIs, theme layers, providers, nav items, or chat persistence), or when wiring an existing feature into the shell instead of hardcoding it.
+---
+
+A `ChatModule` is how features plug into a LYKOMI UI app. The shell stays
+generic; modules contribute everything feature-specific. Never hardcode
+feature wiring into the shell — compose it as a module.
+
+## The contract (from `@lykomi/web-shell`)
+
+```ts
+import { defineChatModule, type ChatModule } from "@lykomi/web-shell";
+
+export const myModule = defineChatModule({
+  name: "my-feature",
+  useInit, // hook body run inside the layout — cross-store sync, nav registration
+  toolUIs, // ReactNode inside <AGUIRuntimeProvider> — makeAssistantToolUI instances
+  layoutExtras, // ReactNode inside the layout — banners, dialogs, popovers
+  wrappers, // ComponentType[] applied outer→inner — context providers
+  useThemeLayers, // hook returning ThemeLayer[] — stacked on the static theme
+  pages, // { path, element }[] — appended to Routes (host app wins on collision)
+  fetchInterceptor, // zero-arg installer called before createRoot
+  chatConversation, // URL-driven chat persistence (below)
+});
+```
+
+Then: `bootstrapShell({ modules: [myModule], pages, theme })`.
+
+## Rules that keep modules composable
+
+- `useInit` is a React hook body — rules of hooks apply (no conditionals around it).
+- Sidebar nav is mutated from `useInit` via `useNavStore.getState().setConfig(...)` — there is no declarative nav field.
+- `wrappers` order is outer→inner from the array; the shell renders
+  `BrowserRouter → AuthProvider → wrappers → AGUIRuntimeProvider → toolUIs → Routes`.
+- Host-app `pages` beat module `pages` on path collision — never rely on a module owning `/`.
+- Chat persistence: provide `chatConversation` with `pathPattern` (regex capturing the conversation id), optional `useStickyConversationId()` (keeps the runtime alive across non-chat navigation), and `buildHistoryAdapter({ urlMatch, aguiThreadId })` returning an assistant-ui `ThreadHistoryAdapter`. Selection: URL match → first registered config → in-memory.
+- Tool UIs use `makeAssistantToolUI(...)` (assistant-ui 0.15.x) and are registered by rendering them inside `toolUIs`.
+
+## Verify before writing
+
+Check the current types in `@lykomi/web-shell` (the package's
+`.d.ts` or [`packages/web-shell/AGENTS.md`](https://github.com/lykomi/ui/blob/main/packages/web-shell/AGENTS.md))
+— the module contract is pre-1.0 and evolves. If your change also touches
+`@assistant-ui/*` or `@ag-ui/*` APIs, run the `lykomi-verify-agent-apis`
+skill first.
+
+For multi-step forms or resumable processes, read the wizard/process guidance
+in [the bundled UX contract](references/form-ux.md). It covers the shared
+`ProcessSteps`/`ProcessGuide` pattern, host-authored actions, returning to
+completed steps, locked-state explanations and checking API availability.
+
+## Shared form UX contract
+
+Before authoring form UI, read [the framework form UX contract](references/form-ux.md).
+Follow its defaults unless the user explicitly requests a different UX. This bundled
+reference is generated from `docs/FORM_UX.md`; do not duplicate its rules here.

package/template/_agents/skills/lykomi-author-chat-module/references/PROCESS_GUIDE.md

@@ -0,0 +1,203 @@
+<!-- Generated from docs/FORM_UX.md; do not edit. -->
+
+## Wizards and process guidance
+
+Use `ProcessSteps` for a connected status rail and `ProcessGuide` for that rail
+plus a focused guidance/action panel. This section is the maintained component
+contract; the standalone process guide and skill resources are generated from it.
+Use a wizard for sequential input and a process overview for resumable work;
+independent tasks belong in a task list rather than a misleading sequence.
+
+- Start with `variant="compact"` and expanded guidance for an active task.
+  Collapse only genuinely secondary help; do not hide the required next action. Use `framed` to make the rail and guidance read as
+  one component; omit a duplicate frame inside an existing panel. Vertical
+  rails center as a group while labels remain aligned to the start.
+- Highlight the inspected compact step with a subtle primary fill and primary
+  label; other steps use a quiet neutral surface. Keep the guidance unfilled,
+  with a primary step label identifying its owner. The compact horizontal rail
+  sits above the labels: completed segments and outlined checks use primary,
+  unfinished segments stay neutral. Vertical connectors advance only between
+  two completed steps. Reserve semantic warning/error colors for those states;
+  inspection never changes status. Overview steps retain their selected border.
+- Separate actual progress (`currentStepId`) from the inspected step
+  (`selectedStepId`). Allow explicit navigation to completed steps so users can
+  revise earlier inputs. Supply Back actions when useful. The host owns
+  validation, persistence, permissions and invalidation of dependent results.
+- Author the panel's `content` and `actions` with standard forms and Buttons.
+  Use filled Buttons for the main forward transaction; outlined Buttons for
+  revising completed input and Back. The component must not invent actions,
+  choose their variants, or silently run jobs when a step is inspected.
+- Announce actual current-step status changes even while an earlier step is
+  inspected; do not announce whole forms or every progress tick. Running work
+  needs honest task-specific progress rather than a percentage inferred from
+  the step count. Use a task list for work without a meaningful sequence.
+- Use explicit complete/ready/running/blocked/error/skipped/pending statuses.
+  Compact locked steps use a short status; a `message` explains prerequisites
+  on hover and keyboard focus, in detailed view and unfolded guidance. Errors
+  remain visible. Do not communicate state through color alone.
+- Preserve unsaved values while guidance is folded. Hosts persist drafts when
+  navigating between steps; folding is not saving. Use theme semantic tokens,
+  the accessible disclosure and reduced-motion behavior provided by the component.
+- Native TypeScript verifies published installed-package exports. Stored JSX
+  separately verifies the deployed renderer scope. New framework APIs must be
+  published before downstream production consumers import them.
+
+### Shared process and chat context
+
+Opt in with `ProcessGuide agentContext={{ id, label, sourcePage, active }}`. Use a stable process-instance ID scoped by its canonical source page; use a readable process label. `active` is required: the host must set it to `false` for inactive tabs, background panels and builder previews, or unmount the guide. A mounted guide without this prop remains presentation-only. With multiple active guides, pointer or keyboard interaction determines which process the With control highlights; all active process snapshots remain available to the agent.
+
+The same committed host props supply the guide, the With control and the next AG-UI request. Context carries `currentStepId` (execution position), `selectedStepId` (inspected guidance) and each step's identity, status, optionality, selectability, description and blocker. Plain string description/message values are included automatically; for JSX, provide `contextText={{ description, message }}` with the equivalent plain-text guidance. React nodes, input values and callbacks are never scraped or serialized. Expose relevant form data through the normal field/context APIs.
+
+`ui_process_get_context` reads current active processes and identifies the focused process. `ui_process_select_step` takes `processId`, `sourcePage` and `stepId`, validates the live registration and explicit selectability, then calls the same selection handler as a user click. Its `requested` result acknowledges dispatch, not a completed host transition: read live context afterward. It never executes, skips, approves, publishes or completes work. Those transactions remain host-owned, permission-checked tools. The existing `ui_get_context` includes process references too.
+
+Context is refreshed on each user request and by the live read tools; it is not a continuous stream of browser changes into a response already being generated. After navigation or an action, refresh context before giving the next guidance. Sent-message context retains the original snapshot. Automatic live process context is separate from optional user pins and survives the user switching into chat, while inactive/unmounted guides are excluded.
+
+### Status symbols, selection and optionality
+
+Use these exact `ProcessStepStatus` values; do not infer execution state from selection or optionality.
+
+| `status`   | Default label   | Symbol                | Meaning                                                                                             |
+| ---------- | --------------- | --------------------- | --------------------------------------------------------------------------------------------------- |
+| `pending`  | Waiting         | Outlined clock        | Awaiting availability or scheduling; not ready yet. Use `blocked` for a known preventing condition. |
+| `ready`    | Ready           | Open circle           | Available to start, but not started. The inspected ready step adds a centered dot.                  |
+| `running`  | In progress     | Spinner               | Execution has actually started; honor reduced motion.                                               |
+| `complete` | Completed       | Outlined check-circle | Work was completed and accepted by the host.                                                        |
+| `blocked`  | Blocked         | Standalone lock       | A prerequisite or permission prevents execution; explain it with `message`.                         |
+| `error`    | Needs attention | Outlined alert-circle | Failure or invalid result requires correction or retry; keep `message` visible.                     |
+| `skipped`  | Skipped         | Outlined minus-circle | The host recorded an explicit skip decision; do not present it as completed work.                   |
+
+`currentStepId` is the actual process position. `selectedStepId` is the step being inspected; its surface highlights which guidance belongs to it. The dot is an additional selection cue only for `ready`: inspecting a completed, running, blocked or skipped step preserves its status symbol. Without a valid selection, the component inspects the current step. Avoid an ambiguous `active` or `disabled` boolean for these distinct concepts.
+
+`selectable` explicitly permits inspection when `onStepSelect` is provided. It never means executable: a host can allow inspection of a blocked step without permitting its action. Status and `optional` never authorize navigation by themselves.
+
+Set `optional: true` independently of status. Unstarted optional steps use a dashed-circle marker in place of the pending clock or ready open circle. Running, completed, blocked, failed and skipped steps keep their status symbols. The default visible label is `Optional`; localize it using `optionalLabel`. It remains visible at compact density and is included in interactive accessible names. An optional step can still be blocked. Provide host-owned Skip/Back actions through the guidance `actions` slot: the host checks policy, persists the decision, sets `status: "skipped"`, and chooses the new `currentStepId`. There is no automatic skip, persistence or prerequisite resolution in this component. Completion accepts both `complete` and `skipped`, but neither selection nor optionality alone marks a process finished.
+
+### Shared component API for builders
+
+This self-contained contract is available in the bundled skill reference;
+no framework repository checkout is needed. Verify the installed/deployed API
+before authoring because a host may expose an earlier version.
+
+`ProcessSteps` accepts `steps`, `currentStepId`, `selectedStepId`,
+`onStepSelect(id)`, `variant` (`compact` or `overview`, default `compact`),
+`orientation` (`responsive`, `vertical` or `horizontal`, default `responsive`),
+`density` (`comfortable` or `compact`, default `comfortable`), optional
+`showChevrons` (boolean, default false) and an accessible
+`label` (default `Process progress`). Each step has a stable unique string `id`,
+string `label`, and explicit `status`: `pending`, `ready`, `running`, `complete`,
+`blocked`, `error` or `skipped`. Optional fields are `statusLabel` (localized text),
+`description`, `message`, `selectable`, `optional` and `optionalLabel`. Only explicitly selectable steps with
+an `onStepSelect` callback navigate; callbacks never advance actual progress.
+A non-selectable blocked step with a message exposes a focusable tooltip.
+
+`showChevrons` adds decorative separators only to horizontal `compact` navigation.
+Their size and reserved gap follow `density`; the progress track stays above the
+steps. Responsive narrow or explicitly vertical layouts retain their connected vertical
+track, and `overview` is unchanged. Chevrons convey sequence, never status.
+
+Horizontal rails retain readable minimum step widths and scroll inside their own viewport when needed. Overflow alone reveals previous/next buttons and subtle edge fades; swiping, trackpad scrolling and keyboard navigation also work. Scrolling never selects a step or advances progress. Selecting or focusing a step brings it into the rail viewport without scrolling the host page. Manual scrolling is not snapped back to the selected step. Buttons respect reduced motion and RTL. Localize their names with `scrollLabels={{ previous: "Previous steps", next: "Next steps" }}`.
+
+Keep default `orientation="responsive"` for a full wizard: it stacks vertically in narrow containers. Use `orientation="horizontal"` for an embedded progress strip that should remain horizontal even on mobile. Guidance and host content remain outside the scroll viewport. Do not hide steps, truncate essential labels or make the entire page scroll sideways.
+
+Use standalone `ProcessSteps density="compact"` for progress-only display: one
+marker and label per step, with accessible status text. There is no guidance
+panel. `onStepSelect(id)` is entirely host-owned: open a document picker,
+navigate to a page or trigger another permitted action; it need not inspect
+inline guidance. Omit the callback for a passive progress indicator.
+
+`ProcessGuide` accepts the same props and adds per-step `title` (text), plus `content` and
+`actions` (React nodes), plus these guide-level props:
+
+| Prop                                         | Contract                                                                                                                                                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `framed`                                     | Optional themed frame; default false.                                                                                                                                                                              |
+| `headingLevel`                               | 2, 3 or 4; default 3.                                                                                                                                                                                              |
+| `guidance`                                   | `expanded` (default) or `collapsible`.                                                                                                                                                                             |
+| `defaultGuidanceOpen`                        | Initial uncontrolled disclosure state; default false.                                                                                                                                                              |
+| `guidanceOpen`, `onGuidanceOpenChange(open)` | Optional host-controlled disclosure state.                                                                                                                                                                         |
+| `guidanceToggleLabel`                        | Localized disclosure text; default `Guidance & actions`.                                                                                                                                                           |
+| `guidanceTogglePlacement`                    | `guidance` (default) or `step`; compact collapsible guides can place the disclosure in the inspected step. Explicit step selection opens guidance, including reselection. Initial open state remains configurable. |
+| `showPosition`                               | Optional numeric position in guidance; default false. The owning step label remains when the task title differs.                                                                                                   |
+| `formatPosition(index, total)`               | Localized position text when `showPosition` is true; index is one-based.                                                                                                                                           |
+| `completion`                                 | Content shown only when no step is inspected/current and every step is complete or skipped.                                                                                                                        |
+
+The selected step falls back to the current step if its ID is absent/invalid.
+Changing inspected steps remounts their content; hosts must retain drafts outside
+that content. Folding guidance keeps the same inputs mounted. Empty arrays render
+nothing. The component never fetches, saves, authorizes, validates or runs a job.
+
+Example composition, after availability is verified:
+
+```jsx
+<ProcessGuide
+  framed
+  variant="compact"
+  guidance="expanded"
+  currentStepId="review"
+  selectedStepId={inspectedStep}
+  onStepSelect={setInspectedStep}
+  steps={[
+    {
+      id: "documents",
+      label: "Documents",
+      status: "complete",
+      selectable: true,
+      title: "Select the source documents",
+      content: documentFields,
+      actions: (
+        <Button type="button" variant="outline" onClick={openDocumentEditor}>
+          Change documents
+        </Button>
+      ),
+    },
+    {
+      id: "review",
+      label: "Review",
+      status: "ready",
+      selectable: true,
+      description: "Check the findings before confirming.",
+      content: reviewFields,
+      actions: (
+        <Button type="button" onClick={validateAndSaveReview}>
+          Confirm review
+        </Button>
+      ),
+    },
+  ]}
+/>
+```
+
+The host supplies the fields and handlers in this example, including saving
+changes and invalidating results after source edits. In native TypeScript import
+from the published package and its stylesheet. In stored JSX use only verified
+scope symbols without imports.
+
+### Design references
+
+- [USWDS step indicator](https://designsystem.digital.gov/components/step-indicator/):
+  distinguish current/completed/pending and keep explicit headings/navigation.
+- [GOV.UK multiple tasks](https://design-system.service.gov.uk/patterns/complete-multiple-tasks/):
+  resumable work needs clear task statuses and prerequisites.
+- [Carbon progress indicator](https://www.carbondesignsystem.com/building-blocks/core/components/progress-indicator/guidelines):
+  a stable sequence and validation are prerequisites for linear task guidance.
+- [WAI disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/):
+  keyboard operation and expanded state for unfolding guidance.
+
+These inform the design; usability with real users still needs validation.
+
+### List toolbar control density
+
+List toolbars use the shared `Button size="sm"` density for New, grouping,
+Filters, Columns and other text actions. Authored `DataTableToolbar actions`
+use the same primitive and size; do not mix the default-height button into that
+row. Let the button primitive own font family, weight, size, control radius,
+outline surface and interaction states. Table controls must not restyle ordinary
+outline buttons with a different radius, translucent fill or shadow reset.
+Retain meaningful states such as active filters, dashed facet boundaries and
+pressed grouping. Icon-only toolbar controls share the same height and focus
+behavior. Menus and badges retain their own semantic surface treatment.
+
+Verify the rendered toolbar in light/dark themes and at narrow widths. Compare
+computed height, font, weight and radius of authored actions with built-in
+Filters/Columns; using the same component name alone does not establish parity.
+Use CSS and shared primitive variants, without observers or per-button requests.