From b72906dc24ff73f695cb08afeff4187f2091609c Mon Sep 17 00:00:00 2001 From: Rob Levin Date: Thu, 30 Apr 2026 07:46:21 -0500 Subject: [PATCH 1/2] Fix #479: Document Agentic Intent feature with dedicated page, installation subsection, and sidebar entry --- llm.txt | 4 + v2/site/docs/.vitepress/config.mts | 1 + v2/site/docs/agentic-intent.md | 113 +++++++++++++++++++++++++++++ v2/site/docs/installation.md | 26 +++++++ 4 files changed, 144 insertions(+) create mode 100644 v2/site/docs/agentic-intent.md diff --git a/llm.txt b/llm.txt index 4102c24df..eaba5a70d 100644 --- a/llm.txt +++ b/llm.txt @@ -15,6 +15,10 @@ The project provides structured **AI Playbooks** designed for agentic and genera - **Landing Page**: `/v2/playbooks/landing/` - Marketing and hero section layouts. - **Form Association**: `/v2/playbooks/form-association/` - Native form participation with FACE components. +## Agentic Intent + +Every bundled playbook ships with an `sdui.json` file containing machine-readable trigger phrases and component recipes. When a user runs `npx agnosticui-cli context` with playbooks installed, the CLI injects an **AgnosticUI Agentic Intent** section into their AI context file so the assistant knows which playbook layout to use when it recognises a user's UI intent. See `/v2/site/docs/agentic-intent.md` for the full authoring guide and trigger phrase reference. + ## Key Architecture - **Framework**: Built with Lit for web components - **Approach**: CLI-first tool that copies components to your project diff --git a/v2/site/docs/.vitepress/config.mts b/v2/site/docs/.vitepress/config.mts index ddcaf969b..8e7fd3757 100644 --- a/v2/site/docs/.vitepress/config.mts +++ b/v2/site/docs/.vitepress/config.mts @@ -95,6 +95,7 @@ export default defineConfig({ { text: 'AI Playbooks', items: [ + { text: 'Agentic Intent', link: '/agentic-intent' }, { text: 'Playground', link: '/playbooks/' }, { text: 'Login Form', link: '/playbooks/login' }, { text: 'Onboarding Wizard', link: '/playbooks/onboarding' }, diff --git a/v2/site/docs/agentic-intent.md b/v2/site/docs/agentic-intent.md new file mode 100644 index 000000000..78a43e6cb --- /dev/null +++ b/v2/site/docs/agentic-intent.md @@ -0,0 +1,113 @@ +# Agentic Intent + +## Overview: SEO for LLMs + +The same way websites use `` tags so search crawlers understand their content, AgnosticUI structures **playbook recipes** so AI agents understand your UI intent. + +When a user asks their AI assistant "build me a dashboard," the assistant knows to reach for `ag-card` for metric tiles, `ag-tabs` for content sections, and `ag-avatar` in the header, following the proven AgnosticUI Discovery Dashboard Playbook layout. That is the win. + +Agentic Intent is an additive layer on top of the existing playbook system. It does not rewrite your prompt files or change how components work. Each playbook ships with a machine-readable `sdui.json` file that the CLI reads and injects into your AI context. + +## How It Works + +Every AgnosticUI playbook ships with an `sdui.json` file that describes: + +- **Trigger phrases**: natural-language expressions that signal the user wants this pattern +- **Layout recipe**: a plain-English description of the page skeleton +- **Component recipe**: which AgnosticUI components to use and the role each plays +- **Notes**: optional implementation hints with small JSON snippets + +When you run `npx agnosticui-cli context`, the CLI scans `src/playbooks/` for installed playbooks, reads their `sdui.json` files, and injects an **AgnosticUI Agentic Intent** section into your AI context file alongside the component prop references. + +```bash +npx agnosticui-cli context +``` + +If playbooks are present, the CLI announces them: + +``` +Detected 2 installed playbooks (dashboard, login) - including intent recipes. +``` + +No extra flags are needed. The intent section is injected automatically. + +## Bundled Playbooks + +All eight bundled playbooks ship with `sdui.json` agentic intent files. Install any of them with: + +```bash +npx agnosticui-cli playbook --framework +``` + +Then re-run `npx agnosticui-cli context` to pick up the intent recipes. + +| Playbook | Slug | Trigger Phrases | +| --- | --- | --- | +| Login Form | `login` | login, sign in, authentication, auth form, user login, sign up | +| Onboarding Wizard | `onboarding` | onboarding, wizard, multi-step, getting started, user setup, setup flow, step wizard | +| Discovery Dashboard | `dashboard` | dashboard, analytics, metrics, admin panel, overview, data view, home screen | +| Support Center | `support` | support, help center, knowledge base, FAQ, tickets, live chat, customer support, help desk | +| Data Grid | `grid` | data grid, table, sortable list, data table, inventory, admin table, spreadsheet view | +| Blog / Article Reader | `blog` | blog, articles, content listing, post detail, editorial, article reader, reading experience | +| Landing / Marketing Page | `landing` | landing page, marketing, hero section, homepage, marketing page, product page, promotional page | +| Contact Form (FACE) | `form-association` | form, native form, form submission, form validation, contact form, FACE, form associated custom elements | + +## Authoring a Custom sdui.json + +If you have a project-specific playbook, add an `sdui.json` at the root of its directory (e.g. `src/playbooks/my-playbook/sdui.json`) to teach your AI assistant how to use it: + +```json +{ + "$schema": "https://raw.githubusercontent.com/AgnosticUI/agnosticui/master/v2/playbooks/playbook-sdui.schema.json", + "version": 1, + "slug": "my-playbook", + "displayName": "My Playbook", + "description": "One-sentence description of what this playbook demonstrates.", + "intent": { + "triggers": ["my feature", "my page", "relevant phrase"], + "summary": "When the user asks for my feature, refer to the My Playbook layout." + }, + "recipe": { + "layout": "Plain-English description of the page layout skeleton.", + "components": [ + { "component": "AgCard", "role": "Primary content container" }, + { "component": "AgButton", "role": "Primary call-to-action" } + ], + "notes": "Optional: 1-2 small JSON snippets to give the LLM syntax flavor." + } +} +``` + +The CLI reads any `src/playbooks/*/sdui.json` it finds. After creating the file, run `npx agnosticui-cli context` to pick it up. + +### Required Fields + +| Field | Type | Description | +| --- | --- | --- | +| `version` | integer | Schema version (currently `1`). Increment when the shape changes. | +| `slug` | string | Matches the playbook directory name | +| `displayName` | string | Human-readable name shown in the injected context | +| `description` | string | One-sentence description | +| `intent.triggers` | string[] | Natural-language phrases that signal this playbook | +| `intent.summary` | string | One-sentence directive for the LLM | +| `recipe.layout` | string | Plain-English layout description | +| `recipe.components` | array | List of `{ component, role }` objects | + +### Optional Fields + +| Field | Type | Description | +| --- | --- | --- | +| `recipe.notes` | string | Implementation hints and small JSON snippets for syntax flavor | + +## The version Field and Stale Files + +The `version` field tracks schema compatibility. The current expected version is `1`. + +If you later update the CLI to a version that expects a higher `version` number, the CLI warns you: + +``` +sdui.json for 'dashboard' uses schema version 1, expected 2 - recipe may be stale. +Re-install: npx agnosticui-cli playbook dashboard --force +``` + +Re-installing with `--force` replaces `sdui.json` with the latest version while leaving your application code untouched. diff --git a/v2/site/docs/installation.md b/v2/site/docs/installation.md index ff85ba3b5..598a75548 100644 --- a/v2/site/docs/installation.md +++ b/v2/site/docs/installation.md @@ -475,6 +475,32 @@ Use `--output` to write to a custom path instead: npx agnosticui-cli context --output ./docs/agnosticui-context.md ``` +### Agentic Intent: Playbook Recipes + +If you have installed any playbooks (`npx agnosticui-cli playbook `), `ag context` +automatically detects them and injects their intent recipes into your AI context file. + +No extra flags needed. When playbooks are present, the CLI announces them: + +``` +Detected 2 installed playbooks (dashboard, login) - including intent recipes. +``` + +The generated context file gains an **AgnosticUI Agentic Intent** section that tells your +AI assistant which playbook to use and how to compose it when a user expresses a known +UI intent: + +> "When the user asks for a dashboard, use ag-card for metric tiles, ag-avatar in the +> header, and ag-tabs for content sections, following the AgnosticUI Discovery Dashboard +> Playbook layout." + +This transforms the AI context from a prop reference into a **structural mental model**: +the assistant knows not just what components exist, but how to compose them for +recognized UI patterns. + +See [Agentic Intent](/agentic-intent) for the full list of bundled playbooks, trigger +phrases, and how to author a custom `sdui.json` for your own project-specific playbooks. + ## Storybook Integration ::: warning Experimental: Use with Caution From 9056a7f0ed34f1fb20b1a36bf4533d0d7654f2c0 Mon Sep 17 00:00:00 2001 From: Rob Levin Date: Thu, 30 Apr 2026 07:51:17 -0500 Subject: [PATCH 2/2] Fix path: move agentic-intent.md under playbooks/ and update all links to /playbooks/agentic-intent --- llm.txt | 2 +- v2/site/docs/.vitepress/config.mts | 2 +- v2/site/docs/installation.md | 2 +- v2/site/docs/{ => playbooks}/agentic-intent.md | 0 4 files changed, 3 insertions(+), 3 deletions(-) rename v2/site/docs/{ => playbooks}/agentic-intent.md (100%) diff --git a/llm.txt b/llm.txt index eaba5a70d..0190a715f 100644 --- a/llm.txt +++ b/llm.txt @@ -17,7 +17,7 @@ The project provides structured **AI Playbooks** designed for agentic and genera ## Agentic Intent -Every bundled playbook ships with an `sdui.json` file containing machine-readable trigger phrases and component recipes. When a user runs `npx agnosticui-cli context` with playbooks installed, the CLI injects an **AgnosticUI Agentic Intent** section into their AI context file so the assistant knows which playbook layout to use when it recognises a user's UI intent. See `/v2/site/docs/agentic-intent.md` for the full authoring guide and trigger phrase reference. +Every bundled playbook ships with an `sdui.json` file containing machine-readable trigger phrases and component recipes. When a user runs `npx agnosticui-cli context` with playbooks installed, the CLI injects an **AgnosticUI Agentic Intent** section into their AI context file so the assistant knows which playbook layout to use when it recognises a user's UI intent. See `/v2/site/docs/playbooks/agentic-intent.md` for the full authoring guide and trigger phrase reference. ## Key Architecture - **Framework**: Built with Lit for web components diff --git a/v2/site/docs/.vitepress/config.mts b/v2/site/docs/.vitepress/config.mts index 8e7fd3757..51e4864c3 100644 --- a/v2/site/docs/.vitepress/config.mts +++ b/v2/site/docs/.vitepress/config.mts @@ -95,7 +95,7 @@ export default defineConfig({ { text: 'AI Playbooks', items: [ - { text: 'Agentic Intent', link: '/agentic-intent' }, + { text: 'Agentic Intent', link: '/playbooks/agentic-intent' }, { text: 'Playground', link: '/playbooks/' }, { text: 'Login Form', link: '/playbooks/login' }, { text: 'Onboarding Wizard', link: '/playbooks/onboarding' }, diff --git a/v2/site/docs/installation.md b/v2/site/docs/installation.md index 598a75548..293f5056d 100644 --- a/v2/site/docs/installation.md +++ b/v2/site/docs/installation.md @@ -498,7 +498,7 @@ This transforms the AI context from a prop reference into a **structural mental the assistant knows not just what components exist, but how to compose them for recognized UI patterns. -See [Agentic Intent](/agentic-intent) for the full list of bundled playbooks, trigger +See [Agentic Intent](/playbooks/agentic-intent) for the full list of bundled playbooks, trigger phrases, and how to author a custom `sdui.json` for your own project-specific playbooks. ## Storybook Integration diff --git a/v2/site/docs/agentic-intent.md b/v2/site/docs/playbooks/agentic-intent.md similarity index 100% rename from v2/site/docs/agentic-intent.md rename to v2/site/docs/playbooks/agentic-intent.md