diff --git a/AI_INIT.md b/AI_INIT.md index f27f85b..8b2d2e4 100644 --- a/AI_INIT.md +++ b/AI_INIT.md @@ -29,9 +29,9 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi ## 3. Mandatory Reading Before touching any code, you MUST read the following documents in order: -1. [ARCHITECTURE.md](ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol. +1. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) – Detailed communication flows, Dual Heartbeat, and two-phase sync protocol. 2. [extension/README.md](extension/README.md) – Extension components, tab structure, and loading process. -3. [SYNC_GUIDE.md](SYNC_GUIDE.md) – Protocol constants and synchronization requirements. +3. [docs/SYNC_GUIDE.md](docs/SYNC_GUIDE.md) – Protocol constants and synchronization requirements. ## 4. The "Vanilla JS Mirror" Pattern To avoid boot-time race conditions in Manifest V3 without a bundler, the following architectural trade-off is enforced: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8d8c381 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to KoalaSync + +Thank you for your interest in contributing to KoalaSync! We welcome all contributions, from bug reports to new features. + +## Development Workflow + +### 1. Prerequisites +- Node.js (v18+) +- Docker (for local server testing) + +### 2. Setup +1. Clone the repository. +2. Run `npm install` in the root directory to install build dependencies. + +### 3. Protocol Synchronization +KoalaSync uses a "Single Source of Truth" for protocol constants in `shared/constants.js`. +- **CRITICAL**: If you modify the constants, you MUST run the build script: + ```bash + node scripts/build-extension.js + ``` + This will automatically synchronize the changes to the extension and generate the browser-specific bundles in the `dist/` folder. + +### 4. Code Standards +- **Vanilla JS**: The extension must remain dependency-free. Do not add npm packages to the `extension/` directory. +- **Privacy**: Do not add external requests (CDNs, fonts, etc.). +- **Comments**: Maintain the existing documentation style, especially for complex sync logic. + +## Pull Request Process +1. Create a new branch for your feature or bugfix. +2. Ensure your code is tested locally (Chrome and Firefox). +3. Update relevant documentation (e.g., `docs/ARCHITECTURE.md` if you change the protocol). +4. Submit your PR with a clear description of the changes. + +## Security +If you find a security vulnerability, please do not open a public issue. Instead, refer to our `SECURITY.md` for disclosure instructions. diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..6230876 --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,27 @@ +# Privacy Policy + +KoalaSync is built with a **Privacy-First** architecture. We believe that your browsing habits and watch history are your business, not ours. + +## 1. Zero External Requests +The KoalaSync extension and its official marketing website are designed to be completely self-contained. +- **No CDNs**: We do not load scripts or styles from external Content Delivery Networks. +- **No Google Fonts**: We use a modern system font stack to avoid tracking by third-party font services. +- **No Analytics**: There are no tracking pixels, telemetry, or analytics scripts (like Google Analytics or Mixpanel) in the codebase. + +## 2. Data Sovereignty +- **Self-Hostable**: You can host your own relay server using our Docker image, giving you 100% control over your data. +- **Memory-Only State**: The relay server stores all room data in RAM. Nothing is written to a database or disk. When a room is empty, it is purged immediately. +- **No Logs**: The official relay server (`sync.shik3i.net`) does not log user IP addresses or room activity. + +## 3. Extension Permissions +KoalaSync requires the following permissions to function: +- `storage`: To remember your username and server preferences locally. +- `tabs` & `scripting`: To detect video elements on pages you visit so they can be synchronized. +- ``: Necessary because KoalaSync works on any website with a `