From 4e43ebdc5fa2e9a3882d9559cf003a37c6eb9f36 Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Sat, 11 Oct 2025 15:29:03 +0800
Subject: [PATCH] chore: agents.md

---
 .cursor/rules/infra-build.mdc       |  27 ----
 .cursor/rules/project-structure.mdc |  67 ---------
 .github/copilot-instructions.md     | 214 ----------------------------
 .vscode/settings.json               |   2 +-
 AGENTS.md                           | 161 +++++++++++++++++++++
 CLAUDE.md                           | 181 +----------------------
 CODE_OF_CONDUCT.md                  |   2 +-
 env.d.ts                            |  22 +--
 8 files changed, 177 insertions(+), 499 deletions(-)
 delete mode 100644 .cursor/rules/infra-build.mdc
 delete mode 100644 .cursor/rules/project-structure.mdc
 delete mode 100644 .github/copilot-instructions.md
 create mode 100644 AGENTS.md

diff --git a/.cursor/rules/infra-build.mdc b/.cursor/rules/infra-build.mdc
deleted file mode 100644
index b3fc38a..0000000
--- a/.cursor/rules/infra-build.mdc
+++ /dev/null
@@ -1,27 +0,0 @@
----
-globs: *.ts,*.tsx,*.js,*.cjs,*.mjs
-description: Build, lint, and env guidance for this repo
----
-### Build and env
-
-- **Dev**: `npm run dev` starts Vite with base `./` and React SWC, Tailwind v4 plugin. Hash routing is required; use `useHashLocation`.
-- **App build**: `npm run build` runs TypeScript build then Vite static build to `dist/` (site) and then `npm run build:lib`.
-- **Library build**: `vite.lib.config.ts` builds UMD and ES to `dist/lib/` with entry `src/entry.ts`, file name `page-agent`.
-- **Env injection**: `vite.config.ts` defines `import.meta.env.OPEN_ROUTER_*` from real env. When adding new env vars, add them under `define` in `vite.config.ts` and reference via `import.meta.env.*`.
-- **Base path**: keep `base: './'` in both dev and build to make hash routing work under static hosting. If you change it, review `pages/main.tsx` URL logic.
-
-### ESLint & TypeScript
-
-- **Lint**: Config in `eslint.config.js` uses TypeScript ESLint with type‑aware rules, React plugins, and relaxed unsafe checks for rapid iteration. Run `npm run lint` or rely on lint‑staged.
-- **TypeScript**: `tsconfig.app.json` is strict with `noEmit` and bundler resolution. Use `@/*` alias per config. Prefer explicit types on exported functions and public classes.
-
-### Output hygiene
-
-- Never commit changes under `dist/` manually. If you need to test CDN/UMD output locally, run library build and open `dist/index.html` or consume `dist/lib/page-agent.umd.cjs`.
-- Do not import from `dist/` in source files. Always import from `src/`.
-
-### Routing & deploy gotchas
-
-- This site is SPA with hash routing. Ensure hosting serves `index.html` and does not rewrite hash routes.
-- When embedding via CDN bookmarklet, the script is `dist/lib/page-agent.umd.cjs`. Query param `?model=` is parsed in `src/entry.ts`.
-
diff --git a/.cursor/rules/project-structure.mdc b/.cursor/rules/project-structure.mdc
deleted file mode 100644
index 2bf789e..0000000
--- a/.cursor/rules/project-structure.mdc
+++ /dev/null
@@ -1,67 +0,0 @@
----
-alwaysApply: true
----
-### Project structure and navigation map
-
-- **Library entry (CDN/UMD)**: Public script entry is `src/entry.ts`. It attaches `PageAgent` to `window` and auto-initializes if injected via a `<script>` tag. Library build outputs to `dist/lib/` with file name `page-agent.*`.
-
-- **Main Page entry**: `pages/main.tsx` mounts a `wouter` `Router` with `useHashLocation`. Routes delegate to:
-  - `pages/router.tsx` for docs/marketing pages
-  - `pages/test-pages/router.tsx` for internal test pages under `#/test-pages`
-
-- **Docs layout**: Use `pages/components/DocsLayout.tsx` for all docs pages. When adding a new doc page, add it to:
-  - the navigation in `DocsLayout.tsx`, and
-  - the switch in `pages/router.tsx` with `<Header /> + <DocsLayout>...` wrapper
-
-- **Hash routing**: Always use hash routes (e.g. `#/docs/...`). The `Router` is created as:
-  - `createRoot(...).render(<Router hook={useHashLocation}> ...)`
-  - Base URL in dev is `/`; otherwise computed relative to `index.html`. Do not change `vite.config.ts` base from `./` without updating `pages/main.tsx`.
-
-- **Aliases**: Use `@/` as alias for `src/` and `@pages/` as alias for `pages/` (set in both Vite configs). Prefer absolute alias imports over deep relative chains.
-
-- **Styling**: Tailwind v4 is enabled via `@tailwindcss/vite`. Use semantic utility classes; avoid ad‑hoc inline styles.
-
-- **Do not edit generated files**: Never edit anything under `dist/`. Add sources under `src/` and let builds emit artifacts.
-
-- **Event bus**: Type-safe event system for decoupling components, primarily used for PageAgent-UI communication.
-
-### Conventions
-
-- **Routing (wouter)**:
-  - Prefer `<Route path="/segment" component={Page} />` for simple pages; use children form when wrapping with layout.
-  - Keep 404 as the final catch‑all `Route` in `pages/router.tsx`.
-  - For test pages, mount under `#/test-pages` only.
-
-- **Docs pages**: Place in `pages/docs/**/page.tsx`. Export a default React component. Pages are rendered inside `DocsLayout` and must be linked in the sidebar.
-
-- **Typescript**:
-  - TS strict is enabled; however, ESLint relaxes many unsafe rules for DX. Keep exported/public APIs typed explicitly.
-  - JSX runtime is `react-jsx` (React 19).
-
-- **Global objects**: The library exposes `window.PageAgent` and `window.pageAgent`. Guard re‑injection by disposing `window.pageAgent` before re‑creating, as done in `src/entry.ts`.
-
-### Core modules (src/)
-
-- **PageAgent.ts**: Core agent implementation and public API
-- **entry.ts**: Library entry point for CDN/UMD usage
-- **config/**: Configuration constants and settings management
-- **tools/**: Agent tool implementations for web actions and page manipulation
-- **ui/**: User interface components (Panel, SimulatorMask, etc.) for agent visualization
-- **llms/**: LLM integration and communication layer
-- **dom/**: HTML serialization, page analysis utilities, and DOM manipulation helpers
-- **utils/**: Shared utilities including the type-safe event bus system
-- **patches/**: Framework-specific optimizations and compatibility fixes (React, Antd, etc.)
-- **prompts/**: System prompts and LLM instruction templates
-- **i18n/**: Internationalization and language support
-
-### Site structure (pages/)
-
-- **pages/**: Documentation site and marketing pages
-- **pages/test-pages/**: Demo pages for testing agent capabilities
-
-### When adding features
-
-- New docs page: create `pages/docs/<section>/<slug>/page.tsx`, add route and sidebar link.
-- New tool: implement under `src/tools/`, export via `src/tools/index.ts`, wire into `PageAgent` if needed.
-- Visual tweaks: edit under `src/ui/` and keep styles in colocated CSS modules.
-
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
deleted file mode 100644
index 7af2e9f..0000000
--- a/.github/copilot-instructions.md
+++ /dev/null
@@ -1,214 +0,0 @@
-# page-agent AI Coding Instructions
-
-## Project Overview
-
-This project has **TWO SEPARATE PARTS**:
-
-1. **Core Library** (`src/`) - Pure JavaScript AI agent library that can be injected into any webpage
-2. **Marketing Website** (`pages/`) - React web app for landing page and documentation
-
-## Architecture & Tech Stack
-
-### Core Library (`src/`) - Pure JavaScript AI Agent
-
-- **Technology**: Vanilla JavaScript/TypeScript (no React dependency)
-- **Purpose**: AI agent with DOM automation capabilities
-- **Output**: UMD/ES modules via `vite.lib.config.ts`
-- **Key Features**: DOM processing, LLM integration, type-safe event bus
-
-### Marketing Website (`pages/`) - React Web App
-
-- **Technology**: React 19 + TypeScript + Wouter routing + Tailwind CSS v4
-- **Purpose**: Landing page and documentation site
-- **Output**: Static website via `vite.config.ts`
-- **Usage**: Hosted documentation and demos
-
-## Critical Development Workflows
-
-### Dual Build System - Two Separate Projects
-
-```bash
-npm start                    # React website (pages/) development
-npm run build               # Build BOTH library AND website
-npm run build:lib           # Pure JS library only (src/ → dist/lib/)
-npm run build:lib:watch     # Library development with auto-rebuild
-```
-
-### Library Development (Pure JavaScript)
-
-**Working on the core AI agent (`src/`):**
-
-1. Edit pure JavaScript/TypeScript files in `src/`
-2. Use `npm run build:lib:watch` for development
-3. Test via CDN injection: `<script src="dist/lib/page-agent.umd.js"></script>`
-4. No React dependencies allowed in `src/`
-
-### Website Development (React)
-
-**Working on marketing/docs (`pages/`):**
-
-1. Use `npm start` for React development server
-2. Can import from `src/` via `@/` alias to demo library features
-3. Create test pages in `pages/test-pages/` to validate library integration
-
-### DOM Pipeline
-
-1. **DOM Extraction**: `src/dom/` converts live DOM to `FlatDomTree`
-2. **Dehydration**: DOM tree → simplified text representation for LLM
-3. **LLM Processing**: Send text to AI model for action planning
-4. **Indexed Operations**: Map LLM responses back to specific DOM elements via indices
-
-### Event Bus Communication
-
-Use `src/utils/bus.ts` instead of prop drilling for PageAgent ↔ UI communication:
-
-```typescript
-// Emit events from PageAgent
-getEventBus().emit('panel:show', undefined)
-getEventBus().emit('panel:update', { status: 'thinking', message: 'Processing...' })
-
-// Listen in UI components
-getEventBus().on('panel:show', () => panel.show())
-```
-
-## Key Patterns & Conventions
-
-### Strict Module Boundaries
-
-- **Core library** (`src/`): Never import from `pages/` - must remain pure JavaScript
-- **React website** (`pages/`): Can import from `src/` via `@/` alias to demo features
-- **Entry points**: `src/entry.ts` (CDN/UMD), `pages/main.tsx` (React website)
-
-### Manual Route Registration Pattern
-
-Routes in `pages/router.tsx` require explicit definition:
-
-```tsx
-<Route path="/docs/features/dom-operations">
-	<div className="min-h-screen bg-white dark:bg-gray-900">
-		<Header />
-		<DocsLayout>
-			<DomOperations />
-		</DocsLayout>
-	</div>
-</Route>
-```
-
-**Adding new docs pages**: 1) Add route to `router.tsx`, 2) Add nav item to `DocsLayout.tsx`
-
-### Hash Routing Requirement
-
-Uses wouter with `useHashLocation` for static hosting compatibility:
-
-```tsx
-<Router hook={useHashLocation}>  // Always hash-based routes
-```
-
-### CDN Auto-Injection Pattern
-
-Library auto-initializes when injected via script tag:
-
-```html
-<script src="page-agent.js?model=gpt-4"></script>
-```
-
-Query params configure `PageAgentConfig` automatically.
-
-### CSS & Design System
-
-- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
-- Custom CSS variables in `src/index.css` define theme gradients:
-  ```css
-  --theme-color-1: rgb(88, 192, 252);
-  --theme-color-2: rgb(189, 69, 251);
-  ```
-- Design follows modern SaaS aesthetic with blue/purple gradients
-- **Accessibility**: Ensure proper contrast ratios, semantic HTML, ARIA labels
-- Dark mode support throughout via Tailwind `dark:` classes
-- Responsive grid layouts for features and content sections
-
-## File Organization
-
-### Core Library (`src/`)
-
-- **PageAgent.ts**: Core agent implementation and public API
-- **entry.ts**: Library entry point for CDN/UMD usage
-- **config/**: Configuration constants and settings management
-- **tools/**: Agent tool implementations for web actions and page manipulation
-- **ui/**: User interface components (Panel, SimulatorMask, etc.) for agent visualization
-- **llms/**: LLM integration and communication layer
-- **dom/**: HTML serialization, page analysis utilities, and DOM manipulation helpers
-- **utils/**: Shared utilities including the type-safe event bus system
-- **patches/**: Framework-specific optimizations and compatibility fixes (React, Antd, etc.)
-- **prompts/**: System prompts and LLM instruction templates
-- **i18n/**: Internationalization and language support
-
-### Documentation Site (`pages/`)
-
-- `main.tsx` - Site entry point with hash routing setup
-- `router.tsx` - Manual route definitions (requires explicit registration)
-- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
-- `docs/[section]/[topic]/page.tsx` - Documentation pages
-- `test-pages/` - Library integration test pages
-
-## Development Workflow
-
-### Commands
-
-- `npm start` - Development server (Vite)
-- `npm run build` - Production build (TypeScript check + Vite build)
-- `npm run lint` - ESLint with strict TypeScript rules
-
-### Debugging Routing Issues
-
-**Common problem**: Blank pages in docs sections. Debug steps:
-
-1. Verify route exists in `pages/router.tsx`
-2. Check component import path
-3. Test with minimal component first
-4. Verify CSS isn't hiding content (check dark mode classes)
-
-### TypeScript Configuration
-
-- Strict mode enabled with `noUnusedLocals` and `noUnusedParameters`
-- Path alias `@/*` maps to `src/*`
-- ESLint uses strict TypeScript rules but disables some for pragmatism:
-  ```js
-  '@typescript-eslint/no-non-null-assertion': 'off'
-  '@typescript-eslint/no-unsafe-assignment': 'off'
-  ```
-
-## Content & Messaging
-
-- **Tone**: Technical but approachable, targeting web developers
-- **Core value prop**: "一行 CDN 引入，为任何网站添加智能 UI Agent"
-- **Differentiator**: Page-embedded vs external automation (vs browser-use)
-- Feature categories: DOM operations, security, data masking, knowledge injection, model integration
-
-## Code Quality Standards
-
-- Use TypeScript strict mode
-- Prefer functional components with hooks
-- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
-- Consistent file naming: kebab-case for multi-word files
-- Import organization: React imports first, then components, then styles
-
-## Critical Files to Understand
-
-- `pages/router.tsx` - Central routing definition
-- `pages/components/DocsLayout.tsx` - Navigation structure
-- `pages/page.tsx` - Homepage showcasing product features
-- `src/PageAgent.ts` - **Core library**: AI agent class with DOM manipulation
-- `src/dom/dom_tree/index.js` - **DOM extraction engine** (ported from Python)
-- `src/utils/bus.ts` - **Type-safe event bus** for decoupled communication
-- `src/entry.ts` - CDN/UMD entry point with auto-initialization
-- `vite.config.ts` and `vite.lib.config.ts` - Dual build configuration
-- `tsconfig.app.json` - TypeScript strictness settings
-
-## Core Library Architecture
-
-The core library (`src/`) is a standalone AI agent with these key components:
-
-- **PageAgent.ts**: Main agent class managing DOM tree updates, element highlighting, and LLM communication
-- **DOM processing pipeline**: Converts complex web pages into LLM-friendly text while preserving interactive element mappings for precise actions
-- **Event bus system**: Type-safe communication between PageAgent and UI components
diff --git a/.vscode/settings.json b/.vscode/settings.json
index e894e39..3e20df6 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,6 +1,6 @@
 {
 	"editor.fontLigatures": true,
-	"cSpell.words": ["retryable"],
+	"cSpell.words": ["opensource", "retryable"],
 	"markdownlint.config": {
 		// "comment": "Relaxed rules",
 		"default": true,
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..85c131b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,161 @@
+# Instructions for coding assistants
+
+## Project Overview
+
+This is a dual-architecture project with **two separate parts**:
+
+1. **Core Library** (`src/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation
+2. **Demo&docs Website** (`pages/`) - React documentation and landing page
+
+## Development Commands
+
+### Core Commands
+
+```bash
+npm start                    # Start React website development server
+npm run build                # Build both library AND website
+npm run build:lib            # Build pure JS library only (src/ → dist/lib/)
+npm run build:lib:watch      # Library development with auto-rebuild
+npm run lint                 # ESLint with TypeScript strict rules
+```
+
+## Architecture & Critical Patterns
+
+### Dual Build System
+
+- **Website build**: `vite.config.ts` → React SPA with hash routing → `dist/`
+- **Library build**: `vite.lib.config.ts` → UMD/ES modules → `dist/lib/`
+- **Entry points**: `src/entry.ts` (library), `pages/main.tsx` (website)
+
+### Module Boundaries (Critical)
+
+- **Core library** (`src/`): NEVER import from `pages/` - must remain pure JavaScript
+- **Website** (`pages/`): CAN import from `src/` via `@/` alias for demos
+- **Import aliases**: `@/` → `src/`, `@pages/` → `pages/`
+
+### DOM Pipeline
+
+1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
+2. **Dehydration**: DOM tree → simplified text for LLM processing
+3. **LLM Processing**: AI model returns action plans
+4. **Indexed Operations**: Map LLM responses back to specific DOM elements
+
+### Event Bus Communication
+
+Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication:
+
+```typescript
+// Emit from PageAgent
+getEventBus().emit('panel:show')
+getEventBus().emit('panel:update', { status: 'thinking' })
+
+// Listen in UI components
+getEventBus().on('panel:show', () => panel.show())
+```
+
+### Hash Routing Requirement
+
+Uses wouter with `useHashLocation` for static hosting:
+
+```tsx
+<Router hook={useHashLocation}>  // Always hash-based routes
+```
+
+### CDN Auto-Injection Pattern
+
+Library auto-initializes when injected via script tag:
+
+```html
+<script src="page-agent.js?model=gpt-4"></script>
+```
+
+Query params configure `PageAgentConfig` automatically in `src/entry.ts`.
+
+## File Organization
+
+### Core Library (`src/`)
+
+- `entry.ts` - CDN/UMD entry point with auto-initialization
+- `PageAgent.ts` - **Main AI agent class** orchestrating DOM operations
+- `tools/` - Agent tool implementations for web actions
+- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
+- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
+- `patches/` - Framework-specific optimizations (React, Antd compatibility)
+- `llms/` - LLM integration and communication layer
+- `dom/` - HTML serialization and page analysis utilities
+- `config/` - Configuration constants and settings
+
+### Website (`pages/`)
+
+- `main.tsx` - Site entry with hash routing setup
+- `router.tsx` - **Manual route definitions** (requires explicit registration)
+- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
+- `docs/[section]/[topic]/page.tsx` - Documentation pages
+- `test-pages/` - Library integration test pages
+
+## Adding New Features
+
+### New Documentation Page
+
+1. Create `pages/docs/<section>/<slug>/page.tsx`
+2. Add route to `pages/router.tsx` with `<Header /> + <DocsLayout>` wrapper
+3. Add navigation item to `DocsLayout.tsx`
+
+### New Agent Tool
+
+1. Implement under `src/tools/`
+2. Export via `src/tools/index.ts`
+3. Wire into `PageAgent.ts` if needed
+
+### New UI Component
+
+1. Create in `src/ui/` with colocated CSS modules
+2. Use event bus for PageAgent communication
+3. Test via `pages/test-pages/`
+
+## Code Standards
+
+### TypeScript
+
+- Explicit typing for exported/public APIs
+- ESLint relaxes some unsafe rules for rapid iteration
+
+### CSS & Styling
+
+- **Prefer Tailwind CSS over custom CSS**
+- Custom CSS variables for theme gradients in `src/index.css`
+- Dark mode support via `dark:` classes
+- CSS modules for component-specific styles
+
+### Import Organization
+
+- External libraries first
+- Internal modules (`@/`, `@pages/`)
+- Relative imports last
+- Blank lines between groups
+
+## Critical Files to Understand
+
+- `pages/router.tsx` - Central routing definition (manual registration required)
+- `pages/components/DocsLayout.tsx` - Navigation structure
+- `src/PageAgent.ts` - Core AI agent class with DOM manipulation
+- `src/dom/dom_tree/index.js` - DOM extraction engine
+- `src/utils/bus.ts` - Type-safe event bus system
+- `src/entry.ts` - Library entry point for CDN usage
+- `vite.config.ts` / `vite.lib.config.ts` - Dual build configuration
+
+## Debugging Common Issues
+
+### Blank Documentation Pages
+
+1. Verify route exists in `pages/router.tsx`
+2. Check component import path
+3. Verify CSS isn't hiding content (check dark mode classes)
+4. Test with minimal component first
+
+### Library Integration Issues
+
+1. Check `dist/lib/page-agent.umd.js` builds correctly
+2. Test CDN injection with query params
+3. Verify event bus communications are properly typed
+4. Use `pages/test-pages/` for isolated testing
diff --git a/CLAUDE.md b/CLAUDE.md
index c233fa5..43c994c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,180 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is a dual-architecture project with **two separate parts**:
-
-1. **Core Library** (`src/`) - Pure JavaScript/TypeScript AI agent library for browser DOM automation
-2. **Marketing Website** (`pages/`) - React documentation and landing page
-
-## Development Commands
-
-### Core Commands
-
-```bash
-npm start                    # Start React website development server
-npm run build                # Build both library AND website
-npm run build:lib            # Build pure JS library only (src/ → dist/lib/)
-npm run build:lib:watch      # Library development with auto-rebuild
-npm run lint                 # ESLint with TypeScript strict rules
-```
-
-### Development Workflows
-
-- **Library development**: Use `npm run build:lib:watch` while editing `src/`
-- **Website development**: Use `npm start` while editing `pages/`
-- **Testing library**: Inject `dist/lib/page-agent.umd.js` via script tag
-
-## Architecture & Critical Patterns
-
-### Dual Build System
-
-- **Website build**: `vite.config.ts` → React SPA with hash routing → `dist/`
-- **Library build**: `vite.lib.config.ts` → UMD/ES modules → `dist/lib/`
-- **Entry points**: `src/entry.ts` (library), `pages/main.tsx` (website)
-
-### Module Boundaries (Critical)
-
-- **Core library** (`src/`): NEVER import from `pages/` - must remain pure JavaScript
-- **Website** (`pages/`): CAN import from `src/` via `@/` alias for demos
-- **Import aliases**: `@/` → `src/`, `@pages/` → `pages/`
-
-### DOM Pipeline
-
-1. **DOM Extraction**: Convert live DOM to `FlatDomTree` via `src/dom/dom_tree/`
-2. **Dehydration**: DOM tree → simplified text for LLM processing
-3. **LLM Processing**: AI model returns action plans
-4. **Indexed Operations**: Map LLM responses back to specific DOM elements
-
-### Event Bus Communication
-
-Use `src/utils/bus.ts` for decoupled PageAgent ↔ UI communication:
-
-```typescript
-// Emit from PageAgent
-getEventBus().emit('panel:show', undefined)
-getEventBus().emit('panel:update', { status: 'thinking' })
-
-// Listen in UI components
-getEventBus().on('panel:show', () => panel.show())
-```
-
-### Hash Routing Requirement
-
-Uses wouter with `useHashLocation` for static hosting:
-
-```tsx
-<Router hook={useHashLocation}>  // Always hash-based routes
-```
-
-### CDN Auto-Injection Pattern
-
-Library auto-initializes when injected via script tag:
-
-```html
-<script src="page-agent.js?model=gpt-4"></script>
-```
-
-Query params configure `PageAgentConfig` automatically in `src/entry.ts`.
-
-## File Organization
-
-### Core Library (`src/`)
-
-- `entry.ts` - CDN/UMD entry point with auto-initialization
-- `PageAgent.ts` - **Main AI agent class** orchestrating DOM operations
-- `tools/` - Agent tool implementations for web actions
-- `ui/` - UI components (Panel, SimulatorMask) with CSS modules
-- `utils/bus.ts` - **Type-safe event bus** for decoupled communication
-- `patches/` - Framework-specific optimizations (React, Antd compatibility)
-- `llms/` - LLM integration and communication layer
-- `dom/` - HTML serialization and page analysis utilities
-- `config/` - Configuration constants and settings
-
-### Website (`pages/`)
-
-- `main.tsx` - Site entry with hash routing setup
-- `router.tsx` - **Manual route definitions** (requires explicit registration)
-- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
-- `docs/[section]/[topic]/page.tsx` - Documentation pages
-- `test-pages/` - Library integration test pages
-
-## Adding New Features
-
-### New Documentation Page
-
-1. Create `pages/docs/<section>/<slug>/page.tsx`
-2. Add route to `pages/router.tsx` with `<Header /> + <DocsLayout>` wrapper
-3. Add navigation item to `DocsLayout.tsx`
-
-### New Agent Tool
-
-1. Implement under `src/tools/`
-2. Export via `src/tools/index.ts`
-3. Wire into `PageAgent.ts` if needed
-
-### New UI Component
-
-1. Create in `src/ui/` with colocated CSS modules
-2. Use event bus for PageAgent communication
-3. Test via `pages/test-pages/`
-
-## Code Standards
-
-### TypeScript
-
-- Strict mode enabled with `noUnusedLocals`/`noUnusedParameters`
-- Explicit typing for exported/public APIs
-- ESLint relaxes some unsafe rules for rapid iteration
-
-### CSS & Styling
-
-- **Prefer Tailwind CSS over custom CSS**
-- Custom CSS variables for theme gradients in `src/index.css`
-- Dark mode support via `dark:` classes
-- CSS modules for component-specific styles
-
-### Import Organization
-
-- External libraries first
-- Internal modules (`@/`, `@pages/`)
-- Relative imports last
-- Blank lines between groups
-
-## Critical Files to Understand
-
-- `pages/router.tsx` - Central routing definition (manual registration required)
-- `pages/components/DocsLayout.tsx` - Navigation structure
-- `src/PageAgent.ts` - Core AI agent class with DOM manipulation
-- `src/dom/dom_tree/index.js` - DOM extraction engine
-- `src/utils/bus.ts` - Type-safe event bus system
-- `src/entry.ts` - Library entry point for CDN usage
-- `vite.config.ts` / `vite.lib.config.ts` - Dual build configuration
-
-## Environment Variables
-
-Add new environment variables to `vite.config.ts` under `define`:
-
-```typescript
-define: {
-  'import.meta.env.YOUR_VAR': JSON.stringify(process.env.YOUR_VAR),
-}
-```
-
-## Debugging Common Issues
-
-### Blank Documentation Pages
-
-1. Verify route exists in `pages/router.tsx`
-2. Check component import path
-3. Verify CSS isn't hiding content (check dark mode classes)
-4. Test with minimal component first
-
-### Library Integration Issues
-
-1. Check `dist/lib/page-agent.umd.js` builds correctly
-2. Test CDN injection with query params
-3. Verify event bus communications are properly typed
-4. Use `pages/test-pages/` for isolated testing
+@AGENTS.md
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index d3904ed..e290c68 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -69,7 +69,7 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4,
 available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
 ----
diff --git a/env.d.ts b/env.d.ts
index f03ace0..41b21f5 100644
--- a/env.d.ts
+++ b/env.d.ts
@@ -1,15 +1,6 @@
 /// <reference types="vite/client" />
 import type { PageAgent } from './src/PageAgent'
 
-declare global {
-	interface Window {
-		pageAgent?: PageAgent
-		PageAgent: typeof PageAgent
-
-		__PAGE_AGENT_IDS__: string[]
-	}
-}
-
 declare module '*.module.css' {
 	const classes: Record<string, string>
 	export default classes
@@ -19,3 +10,16 @@ declare module '*.md?raw' {
 	const content: string
 	export default content
 }
+
+/**
+ * for local dev and umd demo
+ */
+
+declare global {
+	interface Window {
+		pageAgent?: PageAgent
+		PageAgent: typeof PageAgent
+
+		__PAGE_AGENT_IDS__: string[]
+	}
+}