Update README.md

README.md

@@ -1,3 +1,161 @@
-# hushup
+# 🤫 HushUp - Tame Your Mastodon Timeline
 
-HushUp helps you temporarily mute the most active follows, bringing a little calm back to your timeline.
+Ever spend some time touching grass only to come back to a busy afternoon on the timeline? Wish you could just hit a temporary mute button on accounts having a *really* chatty day without unfollowing them and missing their future gems?
+
+HushUp is a simple Python script designed to help you manage timeline noise by identifying and temporarily muting overly active accounts, based on your preferences.
+
+## Features
+
+* **Intelligent Activity Detection:** Automatically identifies accounts posting a little too much.
+* **Temporary Muting:** Silences noisy accounts for a configurable duration, bringing them back automatically.
+* **Easy Setup:** Quick first-time registration with your Mastodon instance.
+* **Customizable:** Fine-tune mute duration, activity thresholds, and API behavior via environment variables.
+* **API Friendly:** Designed with Mastodon API rate limits in mind, with sensitive defaults and automatic backoff.
+
+## Get Started
+
+As long as Python doesn't freak you out, getting HushUp running is a breeze.
+
+### Installation (conda recommended)
+
+Using `conda` helps keep your project dependencies tidy.
+
+```bash
+# Create a dedicated conda environment
+conda create -n hushup python=3.10
+
+# Activate your new environment
+conda activate hushup
+
+# Install HushUp's dependencies
+pip install -r requirements.txt
+```
+
+### First-Time Setup & Authorization
+
+You'll need to authorize HushUp to access your Mastodon account. This step only needs to be done once.
+
+```bash
+# Run the initial setup process
+python hushup.py --register
+```
+
+Follow the prompts:
+1.  Enter your Mastodon instance URL (e.g., `https://mastodon.social`).
+2.  HushUp will provide you with a URL. Open this in your browser, authorize the application, and you'll get an authorization code.
+3.  Paste the authorization code back into your terminal when prompted.
+
+HushUp will save your credentials securely for future use.
+
+### Configuration (`.env` file)
+
+After successfully registering, HushUp will create a `.env` file in the project directory. This is where you can customize its behavior. Open this file with your favorite text editor and tweak the settings to your liking:
+
+```ini
+# API Performance Settings - Adjust these if you encounter rate limits often or need faster processing
+HUSHUP_MAX_REQUESTS=40          # Maximum number of API requests to fetch timeline data per run (default: 20)
+HUSHUP_ITEMS_PER_REQUEST=100    # How many items (toots) to request in each API call (default: 80)
+HUSHUP_RATE_LIMIT_DELAY=1.0     # Short delay between API calls to stay under limits (default: 0.5)
+
+# Behavior Settings - Control how HushUp decides who to mute and for how long
+HUSHUP_MUTE_DURATION=3600       # How long to mute identified accounts, in seconds (default: 21600 = 6 hours)
+HUSHUP_MIN_ACTIVITIES=20        # The activity threshold: mute accounts that have posted *at least* this many times in the analyzed period (default: 10)
+```
+
+*Remember to save the `.env` file after making changes.*
+
+## Running HushUp
+
+Once set up and configured, running HushUp is straightforward:
+
+```bash
+# Analyze your timeline and apply mutes based on your .env settings
+python hushup.py
+```
+
+You can also override the activity threshold directly from the command line for a specific run:
+
+```bash
+# Analyze and mute accounts with at least 20 activities
+python hushup.py --min_activities 20
+```
+
+The mute duration is controlled by the `HUSHUP_MUTE_DURATION` setting in your `.env` file. It's best to stick with one of Mastodon's default mute values:
+
+  * 5 minutes (300)
+  * 30 minutes (1800)
+  * 1 hour (3600)
+  * 6 hours (21600)
+  * 1 day (86400)
+  * 3 days (259200)
+  * 7 days (604800)
+
+## Advanced Usage
+
+### Re-registering / Clearing Credentials
+
+If you need to connect to a different instance or encounter authorization issues, you can force a fresh registration:
+
+```bash
+# Clear existing credentials and start the registration process over
+python hushup.py --clear --register
+```
+
+### Resetting Configuration
+
+To revert your settings back to the original defaults and go through registration again:
+
+```bash
+# Remove the generated config and credential files
+rm .env clientcred.secret
+
+# Run the registration process, which will also create a new .env with defaults
+python hushup.py --register
+```
+
+## Safety & API Rate Limits
+
+HushUp is designed to be a good Fediverse citizen. The default settings are conservative in order to minimize the risk of hitting API rate limits on your Mastodon instance:
+
+* Defaults limit analysis to around 1,600 toots per run (20 requests × 80 items).
+* A small delay is added between API calls (default 0.5 seconds).
+* HushUp includes automatic rate limit detection and will pause if the API tells it to slow down.
+
+**Important:** Most Mastodon instances have a rate limit of around 300 requests every 5 minutes. While HushUp tries its best, adjusting `HUSHUP_MAX_REQUESTS`, `HUSHUP_ITEMS_PER_REQUEST`, and `HUSHUP_RATE_LIMIT_DELAY` should be done carefully based on your instance's specific limits and your usage frequency.
+
+## Troubleshooting
+
+* **Authorization Errors:** If you see errors related to credentials or authorization, try clearing them and re-registering:
+	```bash
+	python hushup.py --clear --register
+	```
+* **Rate Limit Warnings:**
+	```text
+	WARNING: Rate limited. Waiting 30 seconds...
+	```
+	This means HushUp hit the API limit. The script will automatically wait and retry. If you see this frequently, consider reducing the `HUSHUP_ITEMS_PER_REQUEST` or `HUSHUP_MAX_REQUESTS` in your `.env` file.
+* **Missing Dependencies:** If you get import errors, ensure you've installed the requirements:
+	```bash
+	pip install -r requirements.txt
+	```
+
+## Uninstalling
+
+To remove HushUp and its environment:
+
+```bash
+# Deactivate the conda environment
+conda deactivate
+
+# Remove the conda environment
+conda env remove -n hushup
+
+# Remove configuration and credential files
+rm -rf .env clientcred.secret
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)