feat: bundle versioned AI guidance with WebUI

[Mohamed Mansour (mohamedmansour)]

Why

Installing the full AI reference as a skill creates a separate snapshot that developers must refresh whenever WebUI changes. Bundle the reference with the npm package instead so guidance follows the application's installed version.

Approach

• Keep docs/ai.md as the canonical reference and preserve the /ai documentation URL.
• Copy it into @microsoft/webui during prepack, include it in the tarball, and expose the ./ai.md subpath. The generated copy is not tracked in Git. Ordinary dependency builds do not write it, avoiding the Windows file-lock race caused by parallel example builds.
• Replace the full-reference skill with a 10-line loader that asks the agent to read node_modules/@microsoft/webui/ai.md, reread after upgrades, and report missing guidance. No Node.js or package-manager loading commands are prescribed.
• Update skill discovery and installation guidance, and remove FAST-specific material from the AI reference.

Migration

Existing users run npx skills add microsoft/webui --skill webui-reference once more to replace their snapshot with the loader. Future reference updates arrive with package upgrades. Installing the published package does not regenerate documentation or modify agent configuration; an active agent session still needs to reread after an upgrade.

Validation

• Local cargo xtask check passed, including the parallel example builds and documentation build.
• pnpm --dir packages/webui test: 72 tests passed, including a build-hook regression guard, reference refresh, missing-source failure, and app-local/hoisted resolution coverage.
• The routes example build failed before the fix and passed afterward with an injected EBUSY destination-lock simulation. Native Windows confirmation is delegated to the CI rerun.
• Confirmed skills CLI discovery and installation in an isolated project.
• Used real pnpm pack and offline npm install commands to verify byte-for-byte reference inclusion, then installed a synthetic newer package and confirmed the reference changed while the installed loader's SHA-256 remained identical. Rechecked tarball contents after making generation prepack-only. No package was published.