Cleanup.

triggers/wordtrack/README.md

@@ -0,0 +1,103 @@
+# Wordtrack Trigger
+
+Automatically tracks word usage by users and awards level-ups based on configurable thresholds.
+
+## How It Works
+
+The wordtrack trigger monitors all channel messages and counts occurrences of tracked words across different categories. Users automatically level up when they reach configured thresholds.
+
+## Files
+
+- `wordtrack.sh` - Main trigger script (called automatically on messages)
+- `categories.sh` - Configuration file defining categories, words, and levels
+- `data/<channel>/<nick>.dat` - Per-user tracking data
+
+## Modules
+
+Users can interact with wordtrack using these command modules:
+
+### `.wordtrack-stats [nick]`
+Shows word tracking statistics for yourself or another user.
+
+Example:
+```
+.wordtrack-stats
+.wordtrack-stats alice
+```
+
+Output: `alice's word tracking stats: coffee: Coffee Lover (50/100, 50 to next) | tea: Tea Sipper (12/25, 13 to next)`
+
+### `.wordtrack-leaders <category>`
+Shows top 5 users in a category.
+
+Example:
+```
+.wordtrack-leaders coffee
+.wordtrack-leaders
+```
+
+Output: `Top coffee users: 1. alice: Coffee Lover (50 words) | 2. bob: Coffee Drinker (30 words) | 3. charlie: Coffee Newbie (15 words)`
+
+If no category is provided, lists available categories.
+
+## Configuration
+
+Edit `categories.sh` to add new categories or modify existing ones.
+
+### Adding a New Category
+
+1. Create a word array: `categoryWords=("word1" "word2" "word3")`
+2. Create a levels array: `declare -A categoryLevels=([threshold1]="Level Name" [threshold2]="Level Name")`
+3. Add category to the categories list: `categories=("coffee" "tea" "yournewcategory")`
+
+Example:
+```bash
+# Category: programming
+programmingWords=("code" "coding" "python" "javascript" "rust" "git" "debug")
+
+declare -A programmingLevels=(
+    [10]="Code Newbie"
+    [25]="Junior Dev"
+    [50]="Developer"
+    [100]="Senior Dev"
+    [200]="Code Wizard"
+)
+
+# Add to categories list
+categories=("coffee" "tea" "gaming" "programming")
+```
+
+### Array Structure
+
+- **Word arrays**: Simple indexed arrays containing words to track
+  - Words are matched case-insensitively
+  - Multiple word matches in one message count separately
+
+- **Level arrays**: Associative arrays with threshold as key, level name as value
+  - Keys must be integers representing word counts
+  - Users advance when their count meets or exceeds the threshold
+  - Thresholds can be any positive integer
+
+## Data Format
+
+User data files (`data/<channel>/<nick>.dat`) use simple key=value format:
+
+```
+coffee=45
+tea=12
+gaming=78
+```
+
+## Integration with bot.sh
+
+The wordtrack trigger is called automatically for all channel messages from users not in the ignoreList (bot.sh:254-262). It processes messages after the keywords trigger.
+
+Level-up announcements are sent to the channel automatically when thresholds are crossed.
+
+## Notes
+
+- Users in the `ignoreList` are not tracked
+- Word matching is case-insensitive
+- Multiple occurrences of tracked words in a single message all count
+- Data persists across bot restarts (stored in flat files)
+- Each channel has independent tracking data