issue #479/agentic intent docs

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/playbooks/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

v2/site/docs/.vitepress/config.mts

@@ -95,6 +95,7 @@ export default defineConfig({
       {
         text: 'AI Playbooks',
         items: [
+          { text: 'Agentic Intent', link: '/playbooks/agentic-intent' },
           { text: 'Playground', link: '/playbooks/' },
           { text: 'Login Form', link: '/playbooks/login' },
           { text: 'Onboarding Wizard', link: '/playbooks/onboarding' },

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 <slug>`), `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](/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
 
 ::: warning Experimental: Use with Caution

v2/site/docs/playbooks/agentic-intent.md

@@ -0,0 +1,113 @@
+# Agentic Intent
+
+## Overview: SEO for LLMs
+
+The same way websites use `<meta>` 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 <slug> --framework <react|vue|lit>
+```
+
+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.