docs: document build minifier and warn against editing www/ directly

AI_INIT.md

@@ -21,6 +21,8 @@ KoalaSync is a specialized tool for **synchronized video playback** across multi
 - `extension/`: Browser Extension (Chrome & Firefox, Manifest V3). Contains background service worker, content scripts, and popup UI.
 - `server/`: Node.js Relay Server using Socket.IO (WebSocket-only).
 - `website/`: **Landing Page** & Invitation Bridge (Marketing, Tutorials, and Downloads).
+  - **`build.js`**: Zero-dependency static site compiler. Translates `template.html` + `locales/*.json` → `www/`. Also minifies CSS/JS automatically.
+  - **`www/` is auto-generated**: Never edit files in `www/` directly. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, `locales/*.json`) and run `node website/build.js` to regenerate.
 - `shared/`: **Single Source of Truth** for protocol constants and event names.
 - `scripts/`: Development utilities (e.g., `build-extension.js`).
 - `docker-compose.yml`: Root-level orchestration for the relay server.
@@ -128,6 +130,13 @@ Before starting any task, committing, or pushing, you **MUST** run `git pull --r
 2. Run the build script (`node scripts/build-extension.js`).
 3. Implement the handler in `server/index.js` and `background.js`.
 
+### Making Website Changes
+1. Edit source files in `website/` (`template.html`, `style.css`, `app.js`, `lang-init.js`, or `locales/*.json`).
+2. Run the compiler: `node website/build.js`. This generates the multilingual pages in `www/` and minifies CSS/JS.
+3. Verify the output: `node --check website/www/app.js && node --check website/www/lang-init.js`.
+4. Test locally: `npx serve website/www` or `python3 -m http.server 8080 -d website/www`.
+5. Commit both source changes and the updated `www/` output.
+
 ### Testing Locally
 1. Run the build script: `node scripts/build-extension.js`.
 2. Load `dist/chrome/` as an "Unpacked Extension" in Chrome (or `dist/firefox/` in Firefox).

CONTRIBUTING.md

@@ -44,6 +44,7 @@ KoalaSync uses a "Single Source of Truth" for protocol constants in `shared/cons
 ## Pull Request Process
 1. Create a new branch for your feature or bugfix.
 2. Ensure your code is tested locally (Chrome and Firefox).
+   - For website changes: run `node website/build.js` and verify the output.
 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.
 

website/README.md

@@ -17,6 +17,7 @@ The website handles incoming invitation links. When a user clicks a link like `s
 
 The website is 100% **Static HTML, CSS, and JS**. 
 - **Static i18n Compiler**: The site uses a lightweight, zero-dependency Node.js compiler (`build.js`) to parse dictionary files inside `/locales/` against a single source-of-truth template (`template.html`), outputting the fully deployable static folder to `/www/`.
+- **Build-time Minification**: `build.js` automatically minifies CSS and JS during compilation using a built-in state-machine tokenizer (no npm dependencies). Source files are written unminified — always edit source files, never the generated files in `www/`.
 - **Zero Backend**: No Node.js, PHP, or databases are required to host the compiled website.
 - **Zero Tracking**: All assets (fonts, icons) are self-hosted to prevent third-party tracking.
 - **Responsive**: Fully optimized for mobile with a native-feel hamburger menu.
@@ -68,3 +69,6 @@ sync.koalastuff.net {
    npx serve website/www
    ```
 3. To test the invitation flow locally, navigate to `http://localhost:5000/join.html#join:test-room:test-pass`.
+
+> [!IMPORTANT]
+> **Never edit files inside `website/www/` directly.** This directory is fully auto-generated by `build.js`. Always edit source files (`template.html`, `style.css`, `app.js`, `lang-init.js`, locale files in `locales/`) and re-run `node website/build.js` to apply changes. CSS and JS are minified during the build — editing minified files in `www/` will result in lost changes on the next build.