feat: bundle versioned AI guidance with WebUI

.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "webui",
   "description": "WebUI framework agent skills.",
-  "skills": ["./docs/ai"]
+  "skills": ["./ai"]
 }

.github/skills/code-review/SKILL.md

@@ -312,7 +312,7 @@ Every behavioral change must include corresponding documentation updates. Missin
 |-------|-----|
 | **DESIGN.md updated** | If the change modifies public APIs, protocol fields, behavioral contracts, error variants, or SSR markers, `DESIGN.md` must be updated in the same commit. |
 | **User-facing docs updated** | If the change affects CLI flags, template syntax, component authoring, routing, or integration behavior, `docs/` must be updated. |
-| **AI reference updated** | If the change affects anything a code-generation AI would need to know, `docs/ai/SKILL.md` must be updated. |
+| **AI reference updated** | If the change affects anything a code-generation AI would need to know, `docs/ai.md` must be updated. |
 | **README links to docs portal** | Package READMEs should defer to the docs portal, not duplicate content. |
 | **No stale examples** | Code examples in docs must use current API signatures, flag names, and marker formats. |
 | **docs build passes** | `cd docs && pnpm build` must succeed (catches broken links, unescaped `{{`, missing pages). |

.github/skills/diagnostics/SKILL.md

@@ -144,5 +144,5 @@ with **no** added hot-path work).
       (confirm with a benchmark if it sits near a hot loop).
 - [ ] Tests: a regression test that fails without the error, asserting on the
       `code` (not the prose); JSON stays plain (no `\x1b`).
-- [ ] `DESIGN.md` and `docs/` (incl. `docs/ai/SKILL.md`) updated if the contract or
+- [ ] `DESIGN.md` and `docs/` (incl. `docs/ai.md`) updated if the contract or
       a user-visible code/flag changed.

.github/skills/docs-sync/SKILL.md

@@ -11,19 +11,19 @@ Use this skill whenever a change touches user-visible behavior, APIs, or contrac
 
 | What changed | Update |
 |-------------|--------|
-| CLI flags or commands | `docs/guide/cli/index.md` + `docs/ai/SKILL.md` (Build and run section) |
-| Template syntax or directives | `docs/guide/concepts/directives/` + `docs/ai/SKILL.md` |
-| Component authoring model | `docs/guide/concepts/interactivity.md` + `docs/ai/SKILL.md` |
+| CLI flags or commands | `docs/guide/cli/index.md` + `docs/ai.md` (Build and run section) |
+| Template syntax or directives | `docs/guide/concepts/directives/` + `docs/ai.md` |
+| Component authoring model | `docs/guide/concepts/interactivity.md` + `docs/ai.md` |
 | Hydration markers or mechanism | `docs/guide/concepts/hydration.md` + `DESIGN.md` (WebUI Framework Plugin) |
-| Routing behavior | `docs/guide/concepts/routing.md` + `docs/ai/SKILL.md` |
+| Routing behavior | `docs/guide/concepts/routing.md` + `docs/ai.md` |
 | State management or path resolution | `docs/guide/concepts/state-management/index.md` |
 | Handler API (Rust, Node, FFI) | `docs/guide/concepts/handlers/` + `docs/guide/integrations.md` |
 | Protocol fields or fragment types | `DESIGN.md` (Protocol Specification) |
 | Plugin system (parser or handler) | `docs/guide/concepts/plugins/index.md` + `DESIGN.md` |
 | Performance characteristics | `docs/guide/concepts/performance.md` |
 | Public API (Rust crate, npm package) | `DESIGN.md` + relevant handler/integration docs |
 | Error variants or error messages | `DESIGN.md` |
-| `@microsoft/webui-framework` decorators or API | `docs/guide/concepts/interactivity.md` + `docs/ai/SKILL.md` + `packages/webui-framework/README.md` |
+| `@microsoft/webui-framework` decorators or API | `docs/guide/concepts/interactivity.md` + `docs/ai.md` + `packages/webui-framework/README.md` |
 | `@microsoft/webui-router` behavior | `docs/guide/concepts/routing.md` + `packages/webui-router/README.md` |
 
 ## DESIGN.md rules
@@ -51,7 +51,7 @@ Update `docs/` in the same commit when the change is user-visible:
 ### Public API boundary
 
 Developer documentation (`docs/`, crate/package READMEs, and
-`docs/ai/SKILL.md`) documents only supported public APIs and externally
+`docs/ai.md`) documents only supported public APIs and externally
 observable contracts. Every addition must map to at least one public entry
 point:
 
@@ -77,9 +77,13 @@ Every addition must help developers author, configure, debug, or integrate a
 WebUI application. Do not add release-note-style implementation observations
 to reference docs.
 
-Keep protocol internals out of general user docs. The `docs/ai/SKILL.md` file is the single-page AI reference and should be kept in sync with all other docs.
+Keep protocol internals out of general user docs. The `docs/ai.md` file is the single-page AI reference and should be kept in sync with all other docs.
 
-`docs/ai/SKILL.md` is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from `docs/ai/SKILL.md` rather than duplicating it there.
+`docs/ai.md` is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from `docs/ai.md` rather than duplicating it there.
+
+`ai/SKILL.md` is only the stable loader. Update `docs/ai.md` for authoring changes,
+not the loader or the generated `packages/webui/ai.md`. The package prepack step
+refreshes the generated reference; ordinary builds do not write it.
 
 ## Validation
 

.github/skills/webui-dev/SKILL.md

@@ -57,6 +57,6 @@ webui serve ./src --state ./data/state.json --plugin=webui --watch
 
 The complete guide covering all template syntax, styling and animation rules, anti-patterns, routing, and a pre-flight checklist:
 
-**[docs/ai/SKILL.md](/docs/ai/SKILL.md)**
+**[docs/ai.md](/docs/ai.md)**
 
 Read that file before generating any WebUI code.

DESIGN.md

@@ -5419,6 +5419,26 @@ The `@microsoft/webui` npm package follows the esbuild single-package model:
   `done`, and an optional camel-case descriptor
 - render currently requires the native addon; no WASM render fallback is wired
 
+#### Versioned AI reference
+
+`docs/ai.md` is the canonical application-authoring reference and is served at
+`/ai` on the documentation site. The npm prepack step copies it verbatim
+to `packages/webui/ai.md`; this generated copy is ignored by Git and included in
+the package's `files` allowlist. The `@microsoft/webui/ai.md` export allows
+application-relative package resolution without importing the native runtime.
+Packaging fails if the canonical reference is unavailable. Ordinary dependency
+builds do not generate this package-only file: parallel example builds share the
+same package directory and must not race to overwrite the reference.
+
+`ai/SKILL.md`, discovered through `.claude-plugin/plugin.json`, is a stable loader
+installed once rather than a snapshot of the reference. It instructs agents to
+read `node_modules/@microsoft/webui/ai.md` from the application's installed
+dependencies and reread after upgrades, without prescribing loading commands. Missing
+dependencies and older releases without `ai.md` are reported explicitly, never
+silently replaced with latest-version guidance. Framework contributors read
+`docs/ai.md` directly. The loader and package reference do not require runtime
+network requests or install-time changes to consumers' agent configuration.
+
 ### .NET / NuGet Distribution
 
 The `Microsoft.WebUI` package is the managed .NET binding for `webui-ffi`. It targets `net8.0` and `net9.0`, packs `dotnet/src/Microsoft.WebUI/README.md`, and publishes XML documentation generated from public API comments.

ai/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: webui-reference
+description: Use when writing or reviewing WebUI code. Load the reference for the application's installed WebUI version.
+---
+
+Read and follow `node_modules/@microsoft/webui/ai.md` from the application's
+installed dependencies before writing or reviewing WebUI code.
+
+Reread it after upgrades. If unavailable, report the missing reference instead
+of using cached or latest-version guidance.

crates/webui-press/README.md

@@ -218,7 +218,7 @@ Shadow DOM components can react to the layout via `:host-context([data-layout="f
   "nav": [
     { "text": "Guide",      "link": "/guide/" },
     { "text": "Tutorials",  "link": "/tutorials/" },
-    { "text": "AI",         "link": "/ai", "source": "ai/SKILL.md" },
+    { "text": "AI",         "link": "/ai" },
     { "text": "GitHub",     "link": "https://github.com/me/proj" }
   ],
 
@@ -299,13 +299,13 @@ the URL, point a `nav` entry at the file with `source` (a path relative to
 `contentDir`, using forward slashes):
 
 ```json
-{ "text": "AI", "link": "/ai", "source": "ai/SKILL.md" }
+{ "text": "Reference", "link": "/reference", "source": "reference/README.md" }
 ```
 
-That serves `ai/SKILL.md` at `/ai` instead of `/ai/SKILL`. This is what keeps a
-page installable as an agent skill — the [agent-skill
-spec](https://agentskills.io) requires the file be named `SKILL.md` — while
-keeping its published docs URL stable.
+That serves `reference/README.md` at `/reference` instead of
+`/reference/README`, preserving the source filename while keeping the published
+docs URL stable. Ordinary pages such as `ai.md` already map to `/ai` and do not
+need a `source` override.
 
 ### Shared state
 

docs/.webui-press/config.json

@@ -48,8 +48,7 @@
     },
     {
       "text": "AI",
-      "link": "/ai",
-      "source": "ai/SKILL.md"
+      "link": "/ai"
     },
     {
       "text": "GitHub",

docs/ai/SKILL.md → docs/ai.md

@@ -1,6 +1,5 @@
 ---
 layout: page
-name: webui-reference
 description: Authoritative WebUI framework reference for generating correct application code - template-first authoring rules, template syntax, styling, interactivity, routing, state JSON, and anti-patterns.
 ---
 
@@ -10,9 +9,15 @@ description: Authoritative WebUI framework reference for generating correct appl
 > generate correct WebUI code. Read the Rules first - they are the constraints
 > that most often get violated. Deep-dive links are indexed at the bottom.
 >
-> Install this reference into your agent with
+> Install the loader skill **once** with
 > `npx skills add microsoft/webui --skill webui-reference` - see
 > [AI Coding Agents](/guide/installation#ai-coding-agents).
+> It reads `node_modules/@microsoft/webui/ai.md`, so upgrading `@microsoft/webui`
+> updates the reference without reinstalling the skill.
+>
+> Links starting with `/guide/` or `/tutorials/` refer to the
+> [documentation site](https://microsoft.github.io/webui/), which tracks the
+> current release rather than your installed version.
 
 ## Rules
 
@@ -763,8 +768,6 @@ navigation adopts the response without refetching or parsing templates early.
 Non-router apps use `installInteractionHydration({ load })`. This policy trades
 first-interaction latency for lower startup JS/heap and cannot preserve
 transient user activation or closed-shadow click targets.
-The router remains framework-agnostic: FAST or any other runtime starts through
-`onIntent` and passes the same prepared handle after its own hydration is ready.
 
 | Decorator | Purpose | SSR? | Triggers DOM update? |
 |---|---|---|---|
@@ -1018,9 +1021,6 @@ the router for routed components.
   Document is applied before `</head>`. ShadowRoot-targeted Link CSS is preloaded
   from the head and applied inside its owning root. Static request-reachable
   Shadow roots are preloaded the same way.
-- FAST 2/3 plugins require effective Shadow components. Any effective Light
-  component fails with `fast-light-dom-unsupported`; use the WebUI plugin for
-  global Light DOM.
 
 | Attribute | Example | Description |
 |---|---|---|
@@ -1343,26 +1343,6 @@ resolve before component discovery and compilation; do not manually register
 their components elsewhere. See [WebUI Press named regions](/guide/webui-press)
 for the stable built-in region list and full configuration contract.
 
-**FAST authored templates.** The `fast-v2` and `fast-v3` plugins are pinned to
-FAST major versions 2 and 3, respectively; `fast` is a deprecated alias for
-`fast-v2`. With either versioned plugin, a component file authored as one
-`<f-template name="...">` wrapping one direct inner `<template>` is recognized:
-a non-empty `name` sets the component tag (else the filename without
-`.template.html` is kept), `<f-repeat>` and `<f-when>` provide repetition and
-conditions, and client bindings (`@event`, `:property`, `f-ref`, `f-slotted`, `f-children`) may
-be authored directly on the root `<template>`. The verbatim FAST filename
-`<component>.template.html` is discovered even though its stem has no hyphen,
-registering under the authored `name`. In npm packages, the FAST discovery
-plugin uses Custom Elements Manifest declarations and generated sibling
-`<component>.template.html` files; optional styles use
-`<component>.styles.css` or `<component>.css`. Wrapper shadow options include
-`shadowrootmode` and `shadowrootdelegatesfocus`. A leading generated
-`{{styles}}` marker is reserved for CSS injection. A directive takes only
-`value`; unsupported FAST syntax fails the build. Without a FAST plugin,
-`<f-template>` markup passes through unchanged. See
-[Plugins](/guide/concepts/plugins/) for the complete public authoring and
-package-layout contract.
-
 ```json
 {
   "scripts": {

docs/guide/installation.md

@@ -224,7 +224,12 @@ See the [Routing guide](/guide/concepts/routing) for setup and usage.
 
 ## AI Coding Agents
 
-WebUI publishes its framework reference as an installable [agent skill](https://agentskills.io). Installing it gives GitHub Copilot, Claude Code, Cursor, Codex, and other supported agents the authoring rules WebUI expects — template-first structure, CSS-owned styling, opt-in JavaScript — so generated code follows them instead of falling back to React habits.
+WebUI ships its framework reference inside `@microsoft/webui` as `ai.md`.
+The small `webui-reference` [agent skill](https://agentskills.io) tells GitHub
+Copilot, Claude Code, Cursor, Codex, and other supported agents to read that
+installed reference before working on WebUI code.
+
+**Install the loader once**, after adding `@microsoft/webui` to your project:
 
 <webui-press-tabs>
 <webui-press-tab slot="tab" active>npm</webui-press-tab>
@@ -253,7 +258,21 @@ pnpm dlx skills add microsoft/webui --skill webui-reference
 </webui-press-tab-panel>
 </webui-press-tabs>
 
-The skill lands in `.agents/skills/webui-reference/`, which GitHub Copilot reads directly. Agents that keep their own folder, such as Claude Code, also get a copy in theirs. Useful flags:
+The skill lands in `.agents/skills/webui-reference/`, which GitHub Copilot reads
+directly. The installer also sets it up in agent-specific skill directories
+where needed.
+
+The loader asks the agent to read `node_modules/@microsoft/webui/ai.md` from
+the application's installed dependencies.
+Upgrading `@microsoft/webui` updates the guidance with it. You do not need to
+rerun `skills add` for reference updates. If you upgrade during an agent session,
+ask the agent to reread the installed reference.
+
+If you previously installed the full reference as a skill, run the install
+command above once more in the same scope (project or `-g`) to replace it with
+the loader. Commit a project-local installation to share it with your team.
+
+Useful flags:
 
 | Flag | Effect |
 | ---- | ------ |
@@ -267,8 +286,15 @@ To try the reference in a single session without installing it:
 npx skills use microsoft/webui@webui-reference | copilot
 ```
 
+This also uses the reference from your installed package. Releases predating
+bundled `ai.md`, and Rust-only toolchains without `@microsoft/webui`, need a
+reference from their matching release instead. The loader reports missing
+guidance rather than silently using a newer version.
+
 <webui-blockquote appearance="tip" title="Read it yourself" icon="💡">
 
-The skill is the same document served at [AI Reference](/ai). Read it directly when you want the rules and the anti-patterns without wiring up an agent.
+Read the installed `ai.md` directly, or use [AI Reference](/ai) for the current
+release's rules and anti-patterns without wiring up an agent. The website may
+describe a newer version than your project uses.
 
 </webui-blockquote>

packages/webui/.gitignore

@@ -1,2 +1,3 @@
 test/integration.test.js
+/ai.md
 !bin/

packages/webui/README.md

@@ -16,6 +16,21 @@ API requires that native addon and surfaces loading errors directly. It never
 falls back to a subprocess. Use the `webui` CLI explicitly for filesystem
 builds.
 
+## AI coding agents
+
+The package includes `ai.md`, a framework reference matching the installed
+version. Install the loader skill once:
+
+```bash
+npx skills add microsoft/webui --skill webui-reference
+```
+
+The loader reads `node_modules/@microsoft/webui/ai.md` from your application.
+Package upgrades update the reference without reinstalling the skill. The
+`@microsoft/webui/ai.md` subpath also supports package resolution for hoisted
+dependencies. See [AI Coding Agents](https://microsoft.github.io/webui/guide/installation#ai-coding-agents)
+for migration and setup details.
+
 ## Quick start
 
 ```js

packages/webui/package.json

@@ -15,6 +15,7 @@
     "webui": "bin/webui"
   },
   "files": [
+    "ai.md",
     "bin/",
     "dist/index.*",
     "dist/install.*",
@@ -25,13 +26,15 @@
   "scripts": {
     "build": "tsc",
     "postbuild": "node dist/install.js",
+    "prepack": "node scripts/prepare-ai.js",
     "postinstall": "node --input-type=module -e \"try{await import('./dist/install.js')}catch{}\"",
-    "test": "tsc --project tsconfig.test.json && node --test dist/test/integration.test.js dist/test/native-addon-loading.test.js dist/test/projection-conformance.test.js dist/test/projection-compiler.test.js dist/test/projection-esbuild.test.js dist/test/projection-peers.test.js"
+    "test": "tsc --project tsconfig.test.json && node --test dist/test/ai-reference.test.js dist/test/integration.test.js dist/test/native-addon-loading.test.js dist/test/projection-conformance.test.js dist/test/projection-compiler.test.js dist/test/projection-esbuild.test.js dist/test/projection-peers.test.js"
   },
   "engines": {
     "node": ">=18"
   },
   "exports": {
+    "./ai.md": "./ai.md",
     ".": {
       "import": {
         "types": "./dist/index.d.ts",

packages/webui/scripts/prepare-ai.js

@@ -0,0 +1,9 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { copyFile } from "node:fs/promises";
+
+await copyFile(
+  new URL("../../../docs/ai.md", import.meta.url),
+  new URL("../ai.md", import.meta.url),
+);