updated docs and added AGENT.md

AGENT.md

@@ -0,0 +1,45 @@
+# Project instructions
+
+## Scope
+
+This repository contains the Firefox WebExtension **Proxy Switcher Fork By WT**. It uses Manifest V2, a persistent background script, plain HTML/CSS/JavaScript, and no runtime dependencies.
+
+## Source layout
+
+- `manifest.json` — extension metadata, permissions, icons, popup, options page, and Firefox/Android compatibility.
+- `background.js` — proxy routing, proxy authentication, tab-domain tracking, and runtime message handling.
+- `config-manager.js` — local configuration storage and update API.
+- `popup.html`, `popup.js`, `popup.css` — current-domain quick controls.
+- `options.html`, `options.js`, `options.css` — profiles, domains, management actions, and Advanced Settings.
+- `icons/` — extension icon sizes referenced by `manifest.json`.
+- `Makefile` — build and cleanup commands.
+
+## Development rules
+
+- Keep all configuration local. Do not add telemetry, remote requests, analytics, or external script dependencies.
+- Preserve the `browser.*` WebExtension API style and Manifest V2 compatibility unless the task explicitly requests a migration.
+- Proxy settings are domain-specific. A missing domain entry means direct connection; an entry with `enabled: false` is configured but disabled.
+- Keep popup and options theme behavior consistent. Supported theme values are `system`, `light`, and `dark`.
+- When changing an icon, update every size referenced by the manifest and verify the XPI contains the new paths.
+- Never hand-edit or retain stale `META-INF` signatures after changing files. Build artifacts must be signed again before distribution.
+- Do not commit generated `web-ext-artifacts/` packages unless explicitly requested.
+
+## Validation
+
+Run these checks after source changes:
+
+```sh
+node --check background.js
+node --check config-manager.js
+node --check popup.js
+node --check options.js
+python -m json.tool manifest.json >/dev/null
+```
+
+Build a package with:
+
+```sh
+make build
+```
+
+The resulting XPI is written to `web-ext-artifacts/`. It is unsigned when produced by `web-ext build`; Android installation requires a package signed by Mozilla/AMO.

README.md

@@ -1,99 +1,98 @@
 # Firefox Proxy Switcher
 
-A Firefox extension that allows selective application of proxy servers to specific domains, providing flexible proxy management for different websites.
+Proxy Switcher is a Firefox WebExtension that routes requests for selected domains through HTTP or SOCKS5 proxies. Settings and proxy credentials stay in Firefox local extension storage.
 
 ## Features
 
-- **Domain-specific proxy configuration**: Apply different proxy settings to different domains
+- Configure a different proxy for each domain.
-- **Proxy profiles**: Save and reuse proxy configurations
+- Use HTTP or SOCKS5 proxies.
-- **HTTP and SOCKS5 support**: Support for both HTTP and SOCKS5 proxy types
+- Store optional proxy username and password per domain.
-- **Authentication support**: Username/password authentication for proxies
+- Save reusable proxy profiles.
-- **Tag-based organization**: Organize domains with custom tags
+- Enable or disable a configured domain from the popup.
-- **Quick toggle**: Enable/disable proxy for domains with one click
+- Search domains and filter them by tags.
+- Choose a **System**, **Light**, or **Dark** theme in Advanced Settings.
+- Use the same theme in the options page and popup.
+- Run on Firefox desktop and Firefox Android versions that support the declared minimum version.
 
-## Security and Privacy
+## How it works
 
-This extension is designed with user privacy and security in mind:
+The background script listens to `browser.proxy.onRequest`. It extracts the request's origin domain and returns the matching proxy configuration. Domains without a configuration, and configured domains whose `enabled` value is `false`, use a direct connection. Proxy authentication is supplied only when the matching domain has credentials.
 
-### Data Storage
+The extension does not collect browsing history or send configuration to a server. Domain entries, profiles, theme selection, and credentials are saved with `browser.storage.local`. The extension does not implement an additional encryption layer, so protect the Firefox profile and device that contain the data.
-- All configuration data (domains, profiles, proxy settings) is stored locally in the browser using Firefox's `browser.storage.local` API
-- Proxy credentials (usernames/passwords) are encrypted and stored only in the local browser storage
-- No data is transmitted to external servers or collected by the extension
 
-### Network Permissions
+## Use the popup
-The extension requests the following permissions necessary for its functionality:
 
-- `proxy`: Required to configure and manage proxy settings
+1. Open a website and click the Proxy Switcher toolbar button.
-- `storage`: Required to save user configuration locally
+2. If the domain already has a configuration, use **Use proxy for this domain** to enable or disable it.
-- `tabs`: Required to determine the current domain when configuring proxy settings
+3. For a new domain, enable the switch, enter the proxy host and port, then select **Apply & Reload**.
-- `activeTab`: Required to access the current tab for configuration
+4. Open **Advanced Settings** for the complete domain and profile manager.
-- `webRequest`: Required to handle proxy authentication requests
-- `webRequestBlocking`: Required to intercept and modify network requests for proxy routing
-- `<all_urls>`: Required to apply proxy settings to any website the user visits
 
-### How Proxy Routing Works
+## Advanced Settings
-1. When a user visits a website, the extension checks if that domain has proxy configuration
-2. If configured, the extension routes the traffic through the specified proxy server
-3. If not configured, traffic uses the direct connection (no proxy)
-4. Authentication credentials are only used when required by the proxy server and are transmitted securely
 
-### Security Considerations
+The options page provides:
-- **No data collection**: The extension does not collect, store, or transmit any browsing data
+
-- **Local-only storage**: All settings remain on the user's device
+- Proxy profiles that can be reused while editing domains.
-- **Transparent operation**: Users can see exactly which domains use which proxies
+- Domain entries with proxy type, host, port, optional credentials, tags, and enabled state.
-- **No external dependencies**: The extension works entirely offline once configured
+- Search and tag filtering.
+- Bulk deletion of domains, profiles, or all extension data.
+- Theme selection: **System**, **Light**, or **Dark**.
+
+## Permissions
+
+The manifest requests these permissions:
+
+- `proxy` — route requests through the selected proxy.
+- `storage` — store domains, profiles, theme, and credentials locally.
+- `tabs` and `activeTab` — identify the active tab's domain and reload it after changes.
+- `webRequest` and `webRequestBlocking` — provide proxy authentication credentials.
+- `<all_urls>` — apply the domain routing policy to web requests.
+
+These permissions are used for proxy management. The manifest declares `data_collection_permissions.required` as `none`.
 
 ## Installation
 
-1. Download the extension package
+### Firefox desktop
-2. Open Firefox and navigate to `about:addons`
-3. Click the gear icon and select "Install Add-on From File"
-4. Select the downloaded extension file
-5. The extension will be installed and ready to use
 
-For Firefox Android, install the signed XPI from the extension's AMO page or use
+For a temporary development install:
-Firefox's self-distributed add-on installation flow. The manifest declares Android
-compatibility through `browser_specific_settings.gecko_android`; unsigned local
-packages are still rejected by Firefox's extension signing policy.
 
-### Advanced Settings
+1. Open `about:debugging#/runtime/this-firefox`.
+2. Select **Load Temporary Add-on**.
+3. Choose `manifest.json` or a freshly built XPI.
 
-Open **Advanced Settings** from the extension popup to manage all domains and
+For a normal install, use an XPI signed by Mozilla/AMO. Firefox may reject an unsigned or stale-signed package.
-profiles. The **Theme** selector supports **System**, **Light**, and **Dark** and
-is stored locally for use in both the options page and popup.
 
-## Usage
+### Firefox Android
 
-### Basic Setup
+Firefox Android requires a signed extension package. Submit the build through [addons.mozilla.org/developers](https://addons.mozilla.org/developers/) and download the signed XPI after review, or follow Mozilla's [self-distributed extension instructions](https://extensionworkshop.com/documentation/publish/install-self-distributed/). The manifest includes `browser_specific_settings.gecko_android` so AMO can mark the extension as Android-compatible.
-1. Click the Proxy Switcher icon in the Firefox toolbar
-2. Configure proxy settings for the current domain or access full settings
 
-### Advanced Configuration
+The `proxy.onRequest` API is supported on Firefox Android, but the extension still needs to be tested on the target Firefox version and device.
-1. Right-click the extension icon and select "Options"
-2. Add proxy profiles for reuse across domains
-3. Configure domain-specific proxy settings
-4. Use tags to organize your proxy configurations
 
-## Permissions Explanation
+## Build
 
-### Required Permissions
+Install `web-ext`, then run:
-- **proxy**: Allows the extension to configure Firefox's proxy settings
-- **storage**: Enables saving your proxy configurations locally
-- **tabs**: Lets the extension know which domain you're currently viewing
-- **activeTab**: Provides access to the currently active tab for configuration
-- **webRequest**: Handles authentication with proxy servers
-- **webRequestBlocking**: Intercepts and routes network requests through proxies
-- **<all_urls>**: Applies proxy settings to any website you visit
 
-All permissions are used solely for proxy management and do not enable data collection or tracking.
+```sh
+make build
+```
 
-## Support
+The package is created at `web-ext-artifacts/proxyswitcherforkbywt.xpi`. This local build is not an AMO signature. After changing any file, rebuild and sign again; do not reuse old `META-INF` signature files.
 
-If you encounter issues or have questions:
+To remove generated packages:
-1. Check that all required permissions are granted
-2. Verify your proxy server settings are correct
-3. Ensure the proxy server is accessible from your network
 
-## Version
+```sh
+make clean
+```
 
-Current version: 1.0.1
+## Validation
+
+```sh
+node --check background.js
+node --check config-manager.js
+node --check popup.js
+node --check options.js
+python -m json.tool manifest.json >/dev/null
+```
+
+## Project version
+
+Current version: **1.0.1**