diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16858c3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# Mossy Plugins
+
+A collection of DECAL plugins for Asheron's Call, providing utility overlays and automation features.
+
+ ## Contents
+ - `mossy.sln`: Visual Studio solution containing both projects.
+ - `GearCycler/`: Simple plugin with a UI button to cycle gear (placeholder behavior).
+ - `MosswartMassacre/`: Advanced plugin tracking monster kills, rare discoveries, and offering HTTP/telemetry features.
+ - `packages/`: Vendored NuGet packages (Newtonsoft.Json, YamlDotNet).
+
+ ## Prerequisites
+ - Windows with .NET Framework 4.8
+ - Visual Studio 2017+ (MSBuild Tools 15.0) or equivalent MSBuild environment
+ - DECAL Adapter installed for Asheron's Call
+ - VirindiViewService (included in each project's `lib/` folder)
+
+ ## Setup & Build
+ 1. Clone this repository.
+ 2. Ensure the DECAL and Virindi DLLs are present under `MosswartMassacre/lib/` and referenced by each project.
+ 3. Restore NuGet packages if needed (`nuget restore mossy.sln`).
+ 4. Open `mossy.sln` in Visual Studio and build the solution.
+ 5. The output DLLs will be in each project’s `bin/Debug/` or `bin/Release/` folder.
+ 6. Deploy the plugin DLLs (and any required XML or YAML files) to your DECAL plugin directory.
+
+ ## GearCycler
+ A minimal plugin demonstrating a VirindiViewService-based UI.
+ - UI layout: `GearCycler/ViewXML/mainView.xml`.
+ - Core logic in `GearCycler/GearCore.cs`.
+ - On button click, it logs a chat message; extend the `btnCycle.Hit` handler to add gear-cycling logic.
+
+ ## MosswartMassacre
+ Tracks monster kills and rare drops, with multiple utility features.
+
+ ### Features
+ - **Kill Tracking**: Counts total kills and computes rates (kills/5 min, kills/hour).
+ - **Rare Discoveries**: Increments rare count and can automatically set rare meta state.
+ - **UI Overlay**: Displays stats and provides buttons to reset stats or toggle rare meta.
+ - **Command Interface** (`/mm` commands):
+   - `/mm help` : Show available commands.
+   - `/mm report` : Display current stats in chat.
+   - `/mm loc` : Show current map coordinates.
+   - `/mm reset` : Reset kill counters and timers.
+   - `/mm meta` : Toggle automatic rare meta state.
+   - `/mm http <enable|disable>` : Start/stop local HTTP command server (port 8085).
+   - `/mm remotecommands <enable|disable>` : Listen for remote commands from your allegiance chat.
+   - `/mm telemetry <enable|disable>` : Enable/disable periodic telemetry streaming.
+
+ ### HTTP Command Server
+ - Listens on `http://localhost:8085/`.
+ - Accepts POST data: `target=<player>&command=<text>`, then sends a /tell and executes the command.
+
+ ### Configuration
+ - Per-character YAML config stored at `<PluginDir>/<CharacterName>.yaml`.
+ - Settings include:
+   - `remote_commands_enabled`
+   - `rare_meta_enabled`
+   - `http_server_enabled`
+   - `telemetry_enabled`
+   - `char_tag`
+ - Config is auto-generated on first run; modify it or use UI/commands to update.
+
+ ### Telemetry
+ - Periodically posts JSON snapshots of position and stats to a configurable endpoint.
+ - Configure `Endpoint`, `SharedSecret`, and `IntervalSec` in `Telemetry.cs`.
+
+ ## Dependencies
+ - Decal.Adapter (v2.9.8.3)
+ - Decal.Interop.Core & Decal.Interop.Inject
+ - VirindiViewService
+ - Newtonsoft.Json (v13.0.3)
+ - YamlDotNet (v16.3.0)
+
+ ## Contributing
+ 1. Fork the repository.
+ 2. Create a feature branch.
+ 3. Commit your changes and ensure the solution builds.
+ 4. Submit a pull request with a description of your changes.
+
+ --
+ _This README provides a high-level overview to get up and running quickly._
\ No newline at end of file