docs: add project README with usage, licensing, and context.

README.md

@@ -1,3 +1,145 @@
-# wallos-fetcher
+# 📦 Wallos Fetcher
 
-Wallos Fetcher is a command-line tool designed for fetching and exporting subscription data from your Wallos instance. Wallos is an open-source personal subscription tracker, and this tool simplifies the process of retrieving and exporting your subscription details in various formats.
+Wallos Fetcher is a command-line utility designed to retrieve and export subscription data from a self-hosted [Wallos](https://github.com/WallosApp/Wallos) instance—an open-source personal subscription tracker.
+
+This script helps you keep track of all your recurring expenses and share that information in human-readable or machine-readable formats, making it especially useful for budgeting, personal finance planning, and digital legacy preparation for family members.
+
+---
+
+## ✨ Features
+
+- 📄 **Markdown output by default** – easy to read, easy to share
+- 💾 Export as **Markdown**, **CSV**, or **JSON**
+- 🔍 Optionally include **full subscription details** (e.g., cycle, auto-renew, currency)
+- 🗃 Output to a custom file
+- 🧰 Lightweight, portable, and dependency-minimal (requires `curl` and `jq`)
+
+---
+
+## 🚀 Installation
+
+```bash
+git clone https://git.nickhepler.cloud/nick/wallos-fetcher.git
+cd wallos-fetcher
+chmod +x wallos-fetch.sh
+```
+
+> 🔧 Ensure you have `curl` and `jq` installed.
+
+- **Ubuntu/Debian**:
+  ```bash
+  sudo apt install curl jq
+  ```
+
+- **macOS (Homebrew)**:
+  ```bash
+  brew install curl jq
+  ```
+
+---
+
+## 🧪 Usage
+
+```bash
+./wallos-fetch.sh [options]
+```
+
+### ✅ Example Commands
+
+| Purpose                             | Command                                                |
+|-------------------------------------|---------------------------------------------------------|
+| Default output as Markdown          | `./wallos-fetch.sh`                                     |
+| Export as JSON                      | `./wallos-fetch.sh --json`                              |
+| Export as CSV                       | `./wallos-fetch.sh --csv`                               |
+| Include extended subscription data  | `./wallos-fetch.sh --full`                              |
+| Custom output filename              | `./wallos-fetch.sh --output mysubs.md`                 |
+| Combine options                     | `./wallos-fetch.sh --csv --full --output mysubs.csv`   |
+| Show help                           | `./wallos-fetch.sh --help`                              |
+| Check script version                | `./wallos-fetch.sh --version`                           |
+
+---
+
+## 📄 Output Formats
+
+### 🧾 Markdown (Default)
+
+Designed for human readability and sharing with family members.
+
+Includes:
+
+- A title (`# 🧾 Active Subscriptions Overview`)
+- A short description for context and legacy planning
+- A table of subscriptions with essential or full detail (if `--full` used)
+
+```markdown
+# 🧾 Active Subscriptions Overview
+
+This document lists all recurring subscriptions tied to this household or individual. It includes costs, renewal dates, categories, and payment methods. This record is provided as a reference for financial planning, digital legacy management, or to assist family members in case of emergencies or estate matters.
+
+_Last updated: 2025-04-21_
+
+| ID | Name | Price | Next Payment | Category | Payment Method |
+|----|------|-------|---------------|----------|----------------|
+| 1  | Netflix | 17.99 | 2025-04-21 | Entertainment | Credit Card |
+```
+
+### 📊 CSV
+
+Structured export for use in spreadsheets or data processing tools.
+
+- Default fields: `id,name,price,next_payment,category_name,payment_method_name`
+- `--full` option adds: `currency_id,cycle,auto_renew`, etc.
+
+### 📦 JSON
+
+Raw response data from the Wallos API—useful for backups or integrations.
+
+---
+## 🔐 Authentication
+
+You can set your API key in one of two ways:
+
+### 1. Environment Variable (Recommended)
+
+This is the preferred and more secure method, especially for automation and scripting:
+
+```bash
+export WALLOS_API_KEY="your_api_key_here"
+```
+
+The script will automatically detect this variable and use it if `API_KEY` is not set inside the script.
+
+### 2. Hardcoded in Script (Optional)
+
+Open the `wallos-fetch.sh` file and manually set your API key by replacing this line:
+
+```bash
+API_KEY="${API_KEY:-$WALLOS_API_KEY}"
+```
+
+with:
+
+```bash
+API_KEY="your_api_key_here"
+```
+
+> ⚠️ Be cautious: hardcoding secrets in scripts can pose a security risk if the file is shared or version-controlled.
+
+## 📜 License
+
+This project is licensed under the [GNU General Public License v3.0 or later](https://www.gnu.org/licenses/gpl-3.0.html).
+
+---
+
+## 🤝 Contributions
+
+Feedback, bug reports, and pull requests are welcome!  
+Submit issues or improvements via your Gitea repository.
+
+---
+
+## ❤️ About Wallos
+
+Wallos is an open-source personal subscription manager. Learn more or contribute to the main project here:
+
+🔗 https://github.com/WallosApp/Wallos