Update documentation with current status and add installation instructions

DEVELOPMENT_PLAN.md

@@ -60,6 +60,7 @@ Our network analysis revealed that YouTube's web client uses a `POST` request to
     *   **Status:** **COMPLETED.** Analysis of `pytchat` source code (`api.py`, `core/__init__.py`, `core/pytchat.py`, `config/__init__.py`, `paramgen/liveparam.py`, `paramgen/enc.py`, `util/__init__.py`, `parser/live.py`) has provided a comprehensive understanding of its internal mechanisms. The `pytchat` repository has been mirrored to `https://gitea.ramforth.net/ramforth/pytchat-fork` for easier access.
 3.  **Integration with `rich` Display:**
     *   **Action:** Adapt the existing `rich` display logic from `main.py` to consume messages received from `pytchat`.
+    *   **Status:** **COMPLETED.** The `pytchat_listener.py` script now includes full-width alternating backgrounds, emoji coloring, and persistent unique user colors.
 
 ## Phase 2: Re-exploration of YouTube Data API v3 (Creative Use)
 
@@ -88,4 +89,4 @@ Our network analysis revealed that YouTube's web client uses a `POST` request to
 
 **Prioritization:** All research will prioritize **open-source and Linux-compatible solutions**. Compliance with YouTube's Terms of Service remains a critical factor.
 
-**Next Steps:** The findings from this revised research will be compiled into a structured document to inform the design and implementation of a robust YouTube Live Chat monitoring solution.
+**Next Steps:** The findings from this revised research will be compiled into a structured document to inform the design and implementation of a robust YouTube Live Chat monitoring solution.

INSTALLATION.md

@@ -0,0 +1,63 @@
+# Installation and Usage Instructions
+
+This document provides detailed instructions for setting up and running the `pytchat_listener.py` script for monitoring YouTube Live Chat.
+
+## Prerequisites
+
+*   Python 3.8+
+*   `pip` (Python package installer)
+*   `git` (for cloning the repository)
+
+## Installation Steps
+
+1.  **Clone the Repository:**
+    Open your terminal and clone the project repository from Gitea:
+    ```bash
+    git clone https://gitea.ramforth.net/ramforth/youtube-chat-webhook-v2.git
+    cd youtube-chat-webhook-v2
+    ```
+
+2.  **Create and Activate a Virtual Environment:**
+    It is highly recommended to use a Python virtual environment to manage project dependencies.
+    ```bash
+    python3 -m venv venv
+    ```
+    *   **For Bash/Zsh:**
+        ```bash
+        source venv/bin/activate
+        ```
+    *   **For Fish Shell:**
+        ```bash
+        source venv/bin/activate.fish
+        ```
+
+3.  **Install Dependencies:**
+    With your virtual environment activated, install the required Python packages:
+    ```bash
+    pip install pytchat rich
+    ```
+
+## Usage
+
+1.  **Run the Script:**
+    Ensure your virtual environment is activated, then run the `pytchat_listener.py` script:
+    ```bash
+    python pytchat_listener.py
+    ```
+
+2.  **Enter Video ID:**
+    The script will prompt you to "Enter the YouTube Live Stream Video ID:". Paste the 11-character ID of the live stream you wish to monitor and press Enter.
+
+3.  **Observe Chat:**
+    The script will then start fetching and displaying live chat messages in your terminal.
+
+4.  **Save Chat Log:**
+    To exit the script gracefully, press `Ctrl+C`. You will then be prompted if you want to save the chat log.
+
+## User Colors Persistence (`user_colors.json`)
+
+The script assigns unique, persistent colors to chatters. This mapping is stored in a file named `user_colors.json` in the project directory.
+
+*   If this file does not exist, it will be created automatically.
+*   If it exists, the script will load the previously assigned colors.
+*   You can manually edit this file to change a user's color or reset the mapping.

README.md

@@ -12,7 +12,15 @@ For a detailed breakdown of the revised research and exploration steps, please r
 
 ## Current Status
 
-The `pytchat_listener.py` script has been successfully implemented and tested for basic chat fetching and display.
+The `pytchat_listener.py` script has been successfully implemented and tested for basic chat fetching and display. Key features include:
+
+*   **Full-width alternating backgrounds** for readability.
+*   **Emoji coloring** for standard emojis.
+*   **Persistent unique colors** for chatters across sessions.
+
+## Installation and Usage
+
+For detailed installation and usage instructions, please refer to the [INSTALLATION.md](INSTALLATION.md) file.
 
 ## Dependencies
 
@@ -25,4 +33,4 @@ The `pytchat_listener.py` script has been successfully implemented and tested fo
 
 *   Interactive message sending.
 *   More advanced terminal UI (e.g., `prompt_toolkit` for input).
-*   Web overlay integration.
+*   Web overlay integration.