chore: document GenUI for React developers

.github/genui-docs.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "packages/genui/a2ui/README*.md"
+---
+
+Write `packages/genui/a2ui/README*.md` for external app developers who use A2UI from their own ReactLynx projects, not for contributors developing inside `lynx-stack`. Avoid monorepo setup, Turbo commands, package folder maps, private package names, local sample-server startup, localhost-only endpoints, and repository test commands in these user-facing docs.
+
+When documenting the GenUI workflow, frame the happy path as Catalog -> Agent -> Client. Catalog docs should distinguish the client renderer catalog built with `defineCatalog` / `serializeCatalog` from whatever catalog-reference format an agent backend uses for prompts; do not imply the server accepts the client `SerializedCatalog` payload directly unless a conversion layer exists.
+
+Assume the reader knows React but does not know A2UI. Introduce A2UI as a JSON message protocol for safely asking an agent to assemble approved ReactLynx components, and explain GenUI terms by mapping them back to familiar React ideas such as components, props, state updates, external stores, and event handlers.
+
+When documenting GenUI transport implementations, describe the transport as the adapter between product state and `MessageStore`. Cover both REST and SSE paths, make the SSE `done` event the final validated render source, call out `AbortController` cancellation for prompt and action requests, and warn against passing provider credentials or endpoint overrides from untrusted browser clients.
+
+When documenting GenUI CLI usage, use `npx @lynx-js/a2ui-cli` as the user-facing command prefix. Explain both command families: `generate catalog` for TypeScript-derived catalog artifacts and `generate prompt` for A2UI system prompts. Treat `@lynx-js/a2ui-catalog-extractor` as an internal implementation detail used by the catalog generation command, not as an external API or recommended binary, and remind readers that generated prompts and client catalogs must agree on component names and props.
+
+When documenting the GenUI playground, only present the hosted URL `https://lynx-stack.dev/a2ui/` as the trial path. Do not document local `a2ui-playground` package usage, local server startup, or local playground endpoint overrides in user-facing docs; the package is not planned as a published product surface.
+
+Avoid literal wording such as "recommended shape" / "推荐形状" in user-facing docs. Prefer "interface best practice", "implementation pattern", "接口设计最佳实践", or other product-facing phrases that read naturally to React developers.

.github/genui-website.instructions.md

@@ -0,0 +1,5 @@
+---
+applyTo: "website/sidebars/genui.ts"
+---
+
+Expose the website GenUI guide through the A2UI README-generated pages. Do not add a separate `A2UI Catalog Extractor` sidebar entry or generated website page unless the product direction changes; public extractor behavior should be summarized inside `packages/genui/a2ui/README*.md` and surfaced through the A2UI guide.

packages/genui/a2ui-catalog-extractor/README.md

@@ -2,12 +2,16 @@
 
 English | [简体中文](./readme.zh_cn.md)
 
-`@lynx-js/a2ui-catalog-extractor` turns TypeScript component
-interfaces into A2UI component catalog JSON. You write the public
-component contract once as a TypeScript `interface`, describe it with
-normal TypeDoc comments, and let this package generate the JSON Schema
+`@lynx-js/a2ui-catalog-extractor` is the internal TypeDoc-powered extraction
+engine behind `npx @lynx-js/a2ui-cli generate catalog`. It turns TypeScript component
+interfaces into A2UI component catalog JSON. You write the public component
+contract once as a TypeScript `interface`, describe it with normal TypeDoc
+comments, and run the public `npx @lynx-js/a2ui-cli` command to generate the JSON Schema
 that an A2UI agent can read.
 
+For user-facing scripts, use `npx @lynx-js/a2ui-cli generate catalog`. Treat
+this package as the implementation layer for extraction behavior and tests.
+
 ## What It Does
 
 A2UI catalogs describe what components a renderer supports. For each
@@ -54,18 +58,18 @@ the marked interface.
 
 ### Package manager
 
-Install the extractor as a development dependency:
+Run the public CLI package through `npx`:
 
 ```bash
-pnpm add -D @lynx-js/a2ui-catalog-extractor
+npx @lynx-js/a2ui-cli --help
 ```
 
 Then add a script to your package:
 
 ```json
 {
   "scripts": {
-    "build:catalog": "a2ui-catalog-extractor --catalog-dir src/catalog --out-dir dist/catalog"
+    "build:catalog": "npx @lynx-js/a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog"
   }
 }
 ```
@@ -128,7 +132,7 @@ extractor that this interface should become a catalog component named
 Run:
 
 ```bash
-a2ui-catalog-extractor --catalog-dir src/catalog --out-dir dist/catalog
+npx @lynx-js/a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog
 ```
 
 The extractor scans the catalog directory, finds interfaces marked with
@@ -386,16 +390,14 @@ export interface CardProps {
 
 ## CLI Reference
 
-The package exposes the standalone `a2ui-catalog-extractor` binary. The
-separate `@lynx-js/a2ui-cli` package also exposes this flow as
-`a2ui-cli generate catalog`.
+The public CLI entry point is
+`npx @lynx-js/a2ui-cli generate catalog`. It delegates to this package
+internally.
 
 ### Generate catalog artifacts
 
 ```bash
-a2ui-catalog-extractor [options]
-# or
-a2ui-cli generate catalog [options]
+npx @lynx-js/a2ui-cli generate catalog [options]
 ```
 
 | Option                  | Description                                                                  | Default        |
@@ -413,7 +415,13 @@ all inputs, removes duplicates, sorts them, and then runs TypeDoc.
 The scanner accepts `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, and `.cts`
 files. It ignores `.d.ts`, `node_modules`, `dist`, and `.turbo`.
 
-## Programmatic API
+## Repository-internal Programmatic API
+
+These exports are documented for maintainers of `@lynx-js/a2ui-cli`, extractor
+tests, and repository-internal tooling. They are not the external integration
+surface for product code. Product build scripts should call
+`npx @lynx-js/a2ui-cli generate catalog` instead of importing this package
+directly.
 
 ### Generate components from source files
 
@@ -479,7 +487,7 @@ writeCatalogComponents(components, {
 The equivalent CLI command is:
 
 ```bash
-a2ui-catalog-extractor --typedoc-json typedoc.json --out-dir dist/catalog
+npx @lynx-js/a2ui-cli generate catalog --typedoc-json typedoc.json --out-dir dist/catalog
 ```
 
 ### Create a full A2UI catalog object

packages/genui/a2ui-catalog-extractor/readme.zh_cn.md

@@ -2,10 +2,14 @@
 
 [English](./README.md) | 简体中文
 
-`@lynx-js/a2ui-catalog-extractor` 会把 TypeScript 组件接口转换成 A2UI
-组件 catalog JSON。你只需要用 TypeScript `interface` 写一次组件的公开
-契约，用普通 TypeDoc 注释描述字段，然后让这个包生成 A2UI agent 可以读取的
-JSON Schema。
+`@lynx-js/a2ui-catalog-extractor` 是
+`npx @lynx-js/a2ui-cli generate catalog` 背后的内部 TypeDoc extraction engine。它会把 TypeScript 组件接口转换成 A2UI
+组件 catalog JSON。你只需要用 TypeScript `interface` 写一次组件的公开契约，
+用普通 TypeDoc 注释描述字段，然后通过公开的 `npx @lynx-js/a2ui-cli` 命令生成
+A2UI agent 可以读取的 JSON Schema。
+
+用户脚本请使用 `npx @lynx-js/a2ui-cli generate catalog`。这个包主要作为
+extraction 行为和测试的实现层。
 
 ## 它解决什么问题
 
@@ -51,18 +55,18 @@ agent 哪些 props 合法、哪些 props 必填、哪些 enum 值可用，以及
 
 ### 包管理器
 
-把 extractor 安装为开发依赖：
+通过 `npx` 执行公开 CLI 包：
 
 ```bash
-pnpm add -D @lynx-js/a2ui-catalog-extractor
+npx @lynx-js/a2ui-cli --help
 ```
 
 然后在你的 package 中加入脚本：
 
 ```json
 {
   "scripts": {
-    "build:catalog": "a2ui-catalog-extractor --catalog-dir src/catalog --out-dir dist/catalog"
+    "build:catalog": "npx @lynx-js/a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog"
   }
 }
 ```
@@ -123,7 +127,7 @@ export interface QuickStartCardProps {
 运行：
 
 ```bash
-a2ui-catalog-extractor --catalog-dir src/catalog --out-dir dist/catalog
+npx @lynx-js/a2ui-cli generate catalog --catalog-dir src/catalog --out-dir dist/catalog
 ```
 
 extractor 会扫描 catalog 目录，找到带 `@a2uiCatalog` 的 interface，并为每个
@@ -378,16 +382,12 @@ export interface CardProps {
 
 ## CLI 参考
 
-这个包暴露独立的 `a2ui-catalog-extractor` binary。单独的
-`@lynx-js/a2ui-cli` 包也把这个流程暴露为
-`a2ui-cli generate catalog`。
+公开 CLI 入口是 `npx @lynx-js/a2ui-cli generate catalog`。它会在内部委托给这个包。
 
 ### 生成 catalog artifacts
 
 ```bash
-a2ui-catalog-extractor [options]
-# 或
-a2ui-cli generate catalog [options]
+npx @lynx-js/a2ui-cli generate catalog [options]
 ```
 
 | 选项                    | 说明                                                           | 默认值         |
@@ -405,7 +405,10 @@ a2ui-cli generate catalog [options]
 扫描器接受 `.ts`、`.tsx`、`.js`、`.jsx`、`.mts` 和 `.cts` 文件。它会忽略
 `.d.ts`、`node_modules`、`dist` 和 `.turbo`。
 
-## 编程 API
+## 仓库内部编程 API
+
+这些导出主要面向 `@lynx-js/a2ui-cli` 维护者、extractor 测试和仓库内部工具；它们不是给产品代码接入的外部集成面。
+产品构建脚本应该调用 `npx @lynx-js/a2ui-cli generate catalog`，而不是直接 import 这个包。
 
 ### 从源码文件生成 components
 
@@ -470,7 +473,7 @@ writeCatalogComponents(components, {
 等价的 CLI 命令是：
 
 ```bash
-a2ui-catalog-extractor --typedoc-json typedoc.json --out-dir dist/catalog
+npx @lynx-js/a2ui-cli generate catalog --typedoc-json typedoc.json --out-dir dist/catalog
 ```
 
 ### 创建完整 A2UI catalog 对象

packages/genui/a2ui-cli/README.md

@@ -9,13 +9,13 @@ a system prompt for an A2UI generation agent.
 Generate a system prompt with the built-in A2UI basic catalog:
 
 ```bash
-npx @lynx-js/a2ui-cli@latest generate prompt --out dist/a2ui-system-prompt.txt
+npx @lynx-js/a2ui-cli generate prompt --out dist/a2ui-system-prompt.txt
 ```
 
 Generate catalog artifacts for a custom catalog:
 
 ```bash
-npx @lynx-js/a2ui-cli@latest generate catalog \
+npx @lynx-js/a2ui-cli generate catalog \
   --catalog-dir src/catalog \
   --source src/functions \
   --out-dir dist/catalog
@@ -24,7 +24,7 @@ npx @lynx-js/a2ui-cli@latest generate catalog \
 Generate a system prompt for a custom catalog:
 
 ```bash
-npx @lynx-js/a2ui-cli@latest generate prompt \
+npx @lynx-js/a2ui-cli generate prompt \
   --catalog-dir dist/catalog \
   --catalog-id https://example.com/catalogs/custom/v1/catalog.json \
   --out dist/a2ui-system-prompt.txt
@@ -39,7 +39,8 @@ like `<Component>/catalog.json`.
 
 ### `generate catalog`
 
-Delegates catalog extraction to `@lynx-js/a2ui-catalog-extractor`.
+Uses the internal `@lynx-js/a2ui-catalog-extractor` engine. Keep user-facing
+scripts on `npx @lynx-js/a2ui-cli generate catalog`.
 
 Useful options:
 

packages/genui/a2ui-prompt/README.md

@@ -37,8 +37,7 @@ const prompt = buildA2UISystemPrompt({ catalog });
 
 `readA2UICatalogFromDirectory` expects generated files such as
 `<Component>/catalog.json` and optional function definitions under `functions/`.
-Use `@lynx-js/a2ui-cli generate catalog` or
-`@lynx-js/a2ui-catalog-extractor` to create those artifacts.
+Use `npx @lynx-js/a2ui-cli generate catalog` to create those artifacts.
 
 ## Exports