diff --git a/README.md b/README.md
index 1c90c22..7def0b0 100644
--- a/README.md
+++ b/README.md
@@ -534,6 +534,286 @@ form-testing, automation, ci-cd, static-site, no-backend
 
 ## License
 
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+  - # MockAddress Core: Frontend Address & MAC Test Data Engine (Open Source Core)
+
+> This repository contains the open-source **frontend core engine** of MockAddress, for generating authentic-format test addresses and MAC address data across multiple countries/regions.  
+> Full production site: <https://mockaddress.com/>
+
+## Project Overview
+
+MockAddress Core is a **pure frontend, zero backend dependency** test data engine designed for developers and QA engineers, providing:
+
+- **Authentic-format address data** conforming to official postal standards (verifiable on Google Maps / Apple Maps)
+- Optional **identity fields + credit card fields** (for form/payment flow testing only)
+- **MAC address generation + vendor lookup + IPv6 Link-Local derivation** and other network test data
+
+All core logic runs entirely in the browser and can be deployed to any static hosting environment (GitHub Pages, Cloudflare Pages, Vercel, etc.).
+
+> **Note**: This repository only open-sources the **engine and base styles**.  
+> Large-scale address datasets and production site page templates remain MockAddress private assets for online services.
+
+---
+
+## Key Features
+
+- **Multi-Country/Region Address Generation (Engine Support)**
+  - Supports generating address structures conforming to local postal standards for multiple countries/regions
+  - Address fields include complete information: street, city, state/province, postal code, country, etc.
+  - Can be extended with localized fields based on country (e.g., Japanese address hierarchy, Hong Kong bilingual addresses)
+
+- **Authentic Format & Verifiable**
+  - Address data is based on official postal/statistical data + OpenStreetMap and other public data sources, cleaned and organized
+  - Generated results are designed to be **verifiable on Google Maps / Apple Maps and other mapping services**
+  - Suitable for registration forms, payment pages, tax calculation logic, and other scenarios requiring strict address format validation
+
+- **Optional Identity & Credit Card Fields (Testing Only)**
+  - Optionally generate name, gender, date of birth, occupation, localized ID number formats, etc.
+  - Optionally generate credit card numbers (Luhn-validated), expiration date, CVC, and other fields
+  - All identity/card data is **randomly generated and does not correspond to any real individuals or real cards**
+
+- **Batch Export & Automation-Friendly**
+  - Built-in CSV / JSON export capabilities
+  - Suitable for automated testing, regression testing, CI/CD pipelines for bulk test data injection
+
+- **MAC Tools**
+  - Generate MAC addresses in multiple formats (colon, hyphen, dot, no separator, etc.)
+  - Vendor identification based on OUI dataset
+  - Support for deriving IPv6 Link-Local addresses from MAC addresses
+  - All logic runs locally in the browser, suitable for network testing, device simulation, and script development
+
+- **Pure Frontend, Privacy-First**
+  - No backend service dependency, all logic completed in frontend JS
+  - Optionally save generated results to browser `localStorage`, servers do not store any generated data
+
+---
+
+## Repository Structure
+
+```text
+src/
+  js/
+    address-generator.js     # Address/identity/credit card generation engine
+    mac-generator.js         # MAC generation and vendor lookup
+    storage.js               # Storage, rate limiting, export utilities
+    language-switcher.js     # Multi-language routing and internal link rewriting
+    utils.js                 # General utility functions
+  css/
+    main.css                 # Universal dark theme and base UI component styles
+
+README.md                    # Project documentation (this file)
+LICENSE                      # Open source license (MIT recommended)
+CONTRIBUTING.md              # Contribution guidelines (optional)
+ROADMAP.md                   # Roadmap (optional)
+```
+
+> **Reminder**: **This repository does not include production site HTML files or large-scale data files `data/*.json`**.  
+> These are used for online deployment and are not part of this open-source release.
+
+---
+
+## Usage
+
+### Quick Start
+
+**Option 1: Direct Use (if your data directory is `data/`)**
+
+```html
+<script type="module">
+  import { generateUSAddress } from './src/js/address-generator.js'
+  
+  // Direct use, will automatically detect data/ directory
+  const address = await generateUSAddress('CA')
+  console.log(address)
+</script>
+```
+
+**Option 2: Custom Data Path (Recommended)**
+
+```html
+<script type="module">
+  // 1. Import configuration module
+  import { configure } from './src/js/config.js'
+  import { generateUSAddress } from './src/js/address-generator.js'
+  
+  // 2. Configure your data path
+  configure({
+    dataBasePath: 'my-data/',  // Your data directory
+    autoDetectPaths: false     // Disable auto-detection
+  })
+  
+  // 3. Use normally
+  const address = await generateUSAddress('CA')
+  console.log(address)
+</script>
+```
+
+### Configuration Options
+
+- **`dataBasePath`**: Base path for your data files (e.g., `'my-data/'`, `'/static/data/'`)
+- **`autoDetectPaths`**: Whether to enable automatic path detection (default `true`, suitable for mockaddress.com's multi-language structure)
+
+> **Important**: If you don't call `configure()`, the code will use default behavior, **completely unaffected by mockaddress.com's normal operation**.
+
+### Available Functions
+
+- `generateUSAddress(state)` - US addresses
+- `generateHKAddress(region, isEnglish)` - Hong Kong addresses
+- `generateUKAddress(region)` - UK addresses
+- `generateCAAddress(province)` - Canada addresses
+- `generateJPAddress(prefecture)` - Japan addresses
+- `generateINAddress(state)` - India addresses
+- `generateTWAddress(county)` - Taiwan addresses
+- `generateSGAddress(state)` - Singapore addresses
+- `generateDEAddress(state)` - Germany addresses
+- `generateTaxFreeAddress(state)` - US tax-free state addresses
+- `generateIdentityInfo(address)` - Identity information
+- `generateCreditCardInfo()` - Credit card information (testing only)
+
+For detailed usage instructions, see [`使用说明.md`](./使用说明.md) (Usage Guide in Chinese).
+
+You can also refer to our production site <https://mockaddress.com/> to see real-world usage scenarios and UI design, then customize as needed in your own project.
+
+---
+
+## Deployment Examples: Cloudflare & VPS (Static Hosting)
+
+> The following steps are for developers who want to deploy mockaddress-core themselves, describing only the simplest path for README purposes.
+
+### Deploy with Cloudflare Pages (Recommended for Frontend / Zero Ops Cost Scenarios)
+
+1. Create a repository on GitHub (e.g., `mockaddress-core`), push this project's code to it.
+2. Log in to Cloudflare, go to **Pages**, select "Create a project with Git provider", and bind this repository.
+3. Build settings:
+   - Framework preset: **None / Static Site**
+   - Build command: Leave empty (or `npm run build` if you add a build process later)
+   - Output directory: Set to project root (or your build output directory)
+4. After deployment, ensure:
+   - All JS/CSS load correctly via `<script type="module">` / `<link>` relative paths;
+   - If you have multi-language subdirectory structures (e.g., `/en/`, `/ru/`), maintain the same directory hierarchy in the repository.
+
+> **Note**: If you only want to open-source the core and don't want to expose the full site, you can deploy only a minimal demo page (or just screenshots, directing users to the production site in the README).
+
+### Deploy with VPS + Nginx (Suitable for Existing Servers)
+
+1. Build or organize the static file structure locally (`src/js`, `src/css`, and your HTML entry).
+2. Upload these static files to your VPS (e.g., `/var/www/mockaddress-core` directory).
+3. Configure Nginx site (example):
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    root /var/www/mockaddress-core;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+}
+```
+
+4. Reload Nginx: `nginx -s reload` or use the corresponding service management command.
+5. Open your browser and visit `http://your-domain.com` to confirm address generation/MAC tools and other features work correctly.
+
+> **VPS deployment essence**: Host this set of frontend files as a **pure static site**, no Node.js / PHP / database or other backend environment required.
+
+---
+
+## Data Sources & Authenticity (Brief Overview)
+
+For complete data sources and more detailed authority information, refer to our publicly available llms documentation online. Here is a brief summary:
+
+- Primarily based on official postal/statistical data and geographic data published by various countries
+- Supplemented with open-source geographic data projects such as OpenStreetMap / GeoNames / OpenAddresses
+- Cleaned and randomly combined through custom rules to ensure:
+  - Address structure conforms to local postal standards
+  - Address content is designed to be verifiable on mainstream mapping services
+  - Not directly associated with any real personal identity
+
+---
+
+## Open Source Scope & Non-Open Source Parts
+
+**This repository open-sources the following:**
+
+- Frontend engine logic for address/identity/credit card field generation
+- Frontend logic for MAC generation and vendor lookup
+- Base UI styles (CSS) supporting the above engines
+- General routing tools for multi-language static sites (e.g., `language-switcher.js`)
+
+**The following are not included:**
+
+- Production site HTML page templates and all copy
+- Large-scale address data files (`data/*.json` production datasets)
+- Internal operations scripts, deployment configurations, etc.
+
+---
+
+## Suitable & Unsuitable Use Cases (Important)
+
+**Suitable Use Cases (Examples):**
+
+- Software development and testing environments
+- Form validation logic testing
+- Cross-border e-commerce / cross-border business address form filling simulation
+- UI/UX prototyping and demos
+- Educational demonstrations and technical sharing
+- Network testing and device simulation (MAC tools)
+
+**Unsuitable Use Cases:**
+
+- Real mailing and shipping addresses
+- Long-term real-name account registration and operation
+- Circumventing KYC / risk control / legal regulatory purposes
+- Any illegal or gray-area uses
+
+---
+
+## Roadmap (Example)
+
+Planned improvements for the open-source core (actual roadmap subject to `ROADMAP.md`):
+
+- Provide clearer TypeScript type definitions
+- Split country-specific address generation logic for easier standalone extension/on-demand import
+- Enrich export formats and integration examples for easier CI/CD pipeline integration
+- Add support for more countries/regions' address formats based on community feedback
+
+---
+
+## Online Examples & Contact
+
+- **Production Site (Full Product, Multi-Language)**:
+  - Chinese: <https://mockaddress.com/>
+  - English: <https://mockaddress.com/en/>
+  - Russian: <https://mockaddress.com/ru/>
+  - Spanish: <https://mockaddress.com/es/>
+  - Portuguese: <https://mockaddress.com/pt/>
+- For more background and information about this site, see the About/Help/Blog pages on the site.
+
+If you have any questions or suggestions during use, welcome to participate via Issues or PRs to help improve this frontend test data engine.
+
+---
+
+## GitHub Topics
+
+**Recommended topics for this repository:**
+
+```
+javascript, frontend, address-generator, tax-free-states, global-addresses, 
+multi-language, test-data, devtools, qa, testing, mock-data, 
+us-address, canada-address, hong-kong-address, mac-address, 
+authentic-address, postal-standards, csv-export, json-export, 
+browser-only, privacy-first, openstreetmap, address-validation, 
+form-testing, automation, ci-cd, static-site, no-backend
+```
+
+---
+
+## License
+
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 - For more background and information about this site, see the About/Help/Blog pages on the site.