Merge pull request #365 from alibaba/docs/simplify-contributing

docs: simplify docs

CONTRIBUTING.md

@@ -1,45 +1,14 @@
 # Contributing to PageAgent
 
-> **[A note from the maintainer](https://github.com/alibaba/page-agent/issues/349)** — Please read before opening issues or PRs.
-
 ♥️ We welcome contributions from everyone.
 
-## 🚀 Quick Start
+For local development workflows, setup, local LLM config, extension development, testing on other websites, and more details, see [docs/developer-guide.md](docs/developer-guide.md).
-
-### Development Setup
-
-1. **Prerequisites**
-    - `macOS` / `Linux` / `WSL`
-    - `node.js >= 20` with `npm >= 10`
-    - An editor that supports `ts/eslint/prettier`
-    - Make sure `eslint`, `prettier` and `commitlint` work well. Un-linted code won't pass the CI.
-
-2. **Setup**
-
-    ```bash
-    npm i
-    npm start          # Start demo and documentation site
-    npm run build      # Build libs and website
-    ```
-
-### Project Structure
-
-This is a **monorepo** with npm workspaces containing **4 main packages**:
-
-- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
-- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
-- **Extension** (`packages/extension/`) - Chrome extension for multi-page tasks and browser-level automation
-- **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
-
-> We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required.
-> 
-> - When developing. Use alias so that we don't have to pre-build.
-> - When bundling. Use external and disable ts `paths` alias.
-> - When bundling `IIFE` and `Website`. Bundle everything together.
 
 ## 🤝 How to Contribute
 
-### Reporting Issues
+> **[Maintainer's Note](https://github.com/alibaba/page-agent/issues/349)**
+
+### Opening Issues
 
 - Use the GitHub issue tracker to report bugs or request features
 - Search existing issues before creating new ones
@@ -48,147 +17,24 @@ This is a **monorepo** with npm workspaces containing **4 main packages**:
 
 ### Code Contributions
 
-1. **Fork and Clone**
+1. Follow existing code style and patterns
-
+2. Update documentation as needed
-    ```bash
+3. Add JSDoc for public APIs
-    git clone https://github.com/your-username/page-agent.git
+4. Build and lint everything
-    cd page-agent
+5. Test in our demo website, and on other websites if applicable
-    ```
+6. Include screenshots for UI changes
-
-2. **Create Feature Branch**
-
-    ```bash
-    git checkout -b feat/your-feature-name
-    ```
-
-3. **Make Changes**
-    - Follow existing code style and patterns
-    - Add tests for new functionality
-    - Update documentation as needed
-
-4. **Test Your Changes**
-    - Build and lint everything.
-    - Test in our demo website
-    - Test it on other websites if applicable
-    - `@TODO: test suite`
-
-5. **Commit and Push**
-
-    ```bash
-    git add .
-    git commit -m "feat: add awesome feature"
-    git push origin feat/your-feature-name
-    ```
-
-6. **Create Pull Request**
-    - Provide clear description of changes
-    - Link related issues
-    - Include screenshots for UI changes
-
-## 📝 Code Style
-
-### General Guidelines
-
-- Use TypeScript for type safety
-- Follow existing naming conventions
-- Write meaningful commit messages
-- Keep functions small and focused
-- Add JSDoc for public APIs
 
 ### Vibe Coding with AI
 
-> [Vibe coding](https://en.wikipedia.org/wiki/Vibe_coding)
+- Vibe coding is **NOT** allowed for the core lib or the extension!!!
-
 - Vibe coding is **RECOMMENDED** when maintaining **the demo, the website, the UI and tests**.
-    - We have a [website/AGENTS.md](packages/website/AGENTS.md) for that.
+- Make sure your AI references `AGENTS.md` and `website/AGENTS.md` for better quality.
-- Vibe coding is **NOT** allowed for the core lib!!!
-- NEVER try to vibe coding the MV3 extension!!! It is HELL.
 - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
 
-If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it:
-
-- claude-code (`CLAUDE.md`)
-
-    ```markdown
-    @AGENTS.md
-    ```
-
-- antigravity (`.agent/rules/alias.md`)
-
-    ```markdown
-    ---
-    trigger: always_on
-    ---
-
-    @../../AGENTS.md
-    ```
-
-## 🔧 Development Workflows
-
-### Test With Your Own LLM API
-
-- Create a `.env` file in the repo root with your LLM API config
-
-    ```env
-    LLM_MODEL_NAME=gpt-5.2
-    LLM_API_KEY=your-api-key
-    LLM_BASE_URL=https://api.your-llm-provider.com/v1
-    ```
-
-- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
-
-    ```env
-    LLM_BASE_URL="http://localhost:11434/v1"
-    LLM_API_KEY="NA"
-    LLM_MODEL_NAME="qwen3:14b"
-    ```
-
-    > @see https://alibaba.github.io/page-agent/docs/features/models#ollama for configuration
-
-- **Restart the dev server** to load new env vars
-- If not provided, the demo will use the free testing proxy by default. By using it, you agree to its [terms](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md).
-
-### Extension Development
-
-```bash
-# make sure you ran `npm run build:libs` first
-# and every time you changed the core libs
-npm run dev -w @page-agent/ext
-npm run zip -w @page-agent/ext
-```
-
-- Update `packages/extension/docs/extension_api.md` for API integration details
-
-### Testing on Other Websites
-
-- Start and serve a local `iife` script
-
-    ```bash
-    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js
-    ```
-
-- Add a new bookmark
-
-    ```javascript
-    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
-    ```
-
-- Click the bookmark on any page to load Page-Agent
-
-> Warning: AK in your local `.env` will be inlined in the iife script. Be very careful when you distribute the script.
-
-### Adding Documentation
-
-Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
-
-> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.
-
 ## 🚫 What We Don't Accept
 
 - Breaking changes and large PRs without prior discussion
 - Heavy dependencies to core libs
-- Contributions without proper testing
-- Code that doesn't follow project conventions
 - Dependencies or code with licenses incompatible with MIT
 - Bot or AI-generated pull requests without meaningful human involvement
 
@@ -196,12 +42,6 @@ Ask an AI to help you add documentation to the `website/` package. Follow the ex
 
 By contributing to this project, you agree that your contributions will be licensed under the MIT License.
 
-> CLA is optional.
+---
-
-## 💬 Questions?
-
-- Open a GitHub issue for technical questions
-- Check existing documentation and issues first
-- Be respectful and constructive in discussions
 
 Thank you for helping make PageAgent better! 🎉

README.md

@@ -76,11 +76,11 @@ For more programmatic usage, see [📖 Documentations](https://alibaba.github.io
 
 ## 🤝 Contributing
 
-We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
+We welcome contributions from the community! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [docs/developer-guide.md](docs/developer-guide.md) for local development workflows.
 
-Please read the [maintainer note](https://github.com/alibaba/page-agent/issues/349) and [Code of Conduct](docs/CODE_OF_CONDUCT.md) before opening issues or PRs.
+Please read the [maintainer's note](https://github.com/alibaba/page-agent/issues/349) on principles and current state.
 
-Contributions generated entirely by **bots or agents** without substantial human involvement will **not be accepted**.
+Contributions generated entirely by **bots or AI** without substantial human involvement will **not be accepted**.
 
 ## ⚖️ License
 
@@ -110,8 +110,8 @@ Built something cool with PageAgent? Add it here! Open a PR to share your projec
 
 > These are community projects — not maintained or endorsed by us. Use at your own discretion.
 
-| Project | Description |
+| Project  | Description                                                 |
-| ------- | ----------- |
+| -------- | ----------------------------------------------------------- |
 | _Yours?_ | [Open a PR](https://github.com/alibaba/page-agent/pulls) 🙌 |
 
 ---

docs/developer-guide.md

@@ -0,0 +1,117 @@
+# Developer Guide
+
+This file is for local development workflows.
+
+For contribution rules and expectations, see [../CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## 🚀 Quick Start
+
+### Development Setup
+
+1. **Prerequisites**
+    - `macOS` / `Linux` / `WSL`
+    - `node.js >= 20` with `npm >= 10`
+    - An editor that supports `ts/eslint/prettier`
+    - Make sure `eslint`, `prettier` and `commitlint` work well. Un-linted code won't pass the CI.
+
+2. **Setup**
+
+    ```bash
+    npm i
+    npm start          # Start demo and documentation site
+    npm run build      # Build libs and website
+    ```
+
+## 📦 Project Structure
+
+This is a **monorepo** with npm workspaces containing **4 main packages**:
+
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
+- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **Extension** (`packages/extension/`) - Chrome extension for multi-page tasks and browser-level automation
+- **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
+
+> We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required.
+>
+> - When developing. Use alias so that we don't have to pre-build.
+> - When bundling. Use external and disable ts `paths` alias.
+> - When bundling `IIFE` and `Website`. Bundle everything together.
+
+## 🤖 AGENTS.md Alias
+
+If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it:
+
+- claude-code (`CLAUDE.md`)
+
+    ```markdown
+    @AGENTS.md
+    ```
+
+- antigravity (`.agent/rules/alias.md`)
+
+    ```markdown
+    ---
+    trigger: always_on
+    ---
+
+    @../../AGENTS.md
+    ```
+
+## 🔧 Development Workflows
+
+### Test With Your Own LLM API
+
+- Create a `.env` file in the repo root with your LLM API config
+
+    ```env
+    LLM_MODEL_NAME=gpt-5.2
+    LLM_API_KEY=your-api-key
+    LLM_BASE_URL=https://api.your-llm-provider.com/v1
+    ```
+
+- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
+
+    ```env
+    LLM_BASE_URL="http://localhost:11434/v1"
+    LLM_API_KEY="NA"
+    LLM_MODEL_NAME="qwen3:14b"
+    ```
+
+    > @see https://alibaba.github.io/page-agent/docs/features/models#ollama for configuration
+
+- **Restart the dev server** to load new env vars
+- If not provided, the demo will use the free testing proxy by default. By using it, you agree to its [terms](./terms-and-privacy.md).
+
+### Extension Development
+
+```bash
+# make sure you ran `npm run build:libs` first and every time you changed the core libs
+npm run dev -w @page-agent/ext
+npm run zip -w @page-agent/ext
+```
+
+- Update `packages/extension/docs/extension_api.md` for API integration details
+
+### Testing on Other Websites
+
+- Start and serve a local `iife` script
+
+    ```bash
+    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js
+    ```
+
+- Add a new bookmark
+
+    ```javascript
+    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+    ```
+
+- Click the bookmark on any page to load Page-Agent
+
+> Warning: AK in your local `.env` will be inlined in the iife script. Be very careful when you distribute the script.
+
+### Adding Documentation
+
+Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
+
+> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.