diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e86227
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# Prometheus Spigot
+
+Prometheus Spigot exposes server metrics at a configurable HTTP endpoint for Prometheus scrapes. It targets Spigot/Paper 1.21.11 and uses the JDK HTTP server with bearer token auth.
+
+## Install
+
+1. Build the plugin: `./gradlew build`
+2. Copy the JAR from `build/libs/` into your server `plugins/` directory.
+3. Start the server once to generate `plugins/PrometheusSpigot/config.yml` and token.
+
+## Configure
+
+`config.yml` (defaults shown):
+
+```yaml
+http:
+  bind_address: "0.0.0.0"
+  port: 9149
+  path: "/metrics"
+  bearer_token: ""
+metrics:
+  enable_jvm: true
+  enable_process: true
+movement:
+  count_block_changes_only: true
+```
+
+## Scrape Example
+
+```yaml
+scrape_configs:
+  - job_name: spigot
+    metrics_path: /metrics
+    static_configs:
+      - targets: ["server:9149"]
+    authorization:
+      credentials: "<bearer_token>"
+```
+
+## Metrics
+
+Some metrics depend on server implementations (TPS/MSPT, player ping, tile entities). If a method is unavailable on your server build, those metrics are omitted.
+
+| Metric | Type | Labels | Description |
+| --- | --- | --- | --- |
+| spigot_chat_messages_total | counter | none | Total chat messages sent |
+| spigot_player_movements_total | counter | none | Total player movement events |
+| spigot_players_joined_total | counter | none | Total player joins |
+| spigot_players_quit_total | counter | none | Total player quits |
+| spigot_chunk_loads_total | counter | none | Total chunk load events |
+| spigot_chunk_unloads_total | counter | none | Total chunk unload events |
+| spigot_chunks_generated_total | counter | none | Total generated chunks |
+| spigot_plugin_enable_total | counter | none | Total plugin enable events |
+| spigot_plugin_disable_total | counter | none | Total plugin disable events |
+| spigot_blocks_broken_total | counter | material | Blocks broken by material |
+| spigot_player_deaths_total | counter | cause | Player deaths by cause |
+| spigot_player_logins_failed_total | counter | reason | Failed player logins by reason |
+| spigot_commands_blocked_total | counter | command | Blocked commands by name |
+| spigot_commands_executed_total | counter | command,source | Commands executed by source |
+| spigot_players_online | gauge | none | Online player count |
+| spigot_players_max | gauge | none | Max player slots |
+| spigot_worlds_loaded | gauge | none | Loaded world count |
+| spigot_chunks_loaded | gauge | none | Loaded chunk count |
+| spigot_plugins_loaded | gauge | none | Loaded plugin count |
+| spigot_tasks_pending | gauge | none | Pending scheduled tasks |
+| spigot_tasks_running | gauge | none | Active scheduled tasks |
+| spigot_entities_total | gauge | type | Entities by type |
+| spigot_tile_entities_total | gauge | type | Tile entities by type |
+| spigot_player_ping_ms_player | gauge | player | Player ping in milliseconds |
+| spigot_tps | gauge | interval | Server TPS by interval (1m/5m/15m) |
+| spigot_mspt | gauge | none | Average milliseconds per tick |
+| process_uptime_seconds | gauge | none | Process uptime in seconds |
+| jvm_threads | gauge | none | Current JVM thread count |
+| jvm_memory_used_bytes | gauge | area | JVM memory used in bytes |
+| jvm_memory_max_bytes | gauge | area | JVM memory max in bytes |
+| jvm_thread_cpu_seconds_total | counter | none | Total CPU seconds used by JVM threads |
+| jvm_gc_pause_seconds_count | counter | gc | GC pause count |
+| jvm_gc_pause_seconds_total | counter | gc | Total GC pause time |
+| spigot_player_ping_ms_bucket | histogram | le | Player ping histogram buckets |
+| spigot_player_ping_ms_sum | histogram | none | Player ping histogram sum |
+| spigot_player_ping_ms_count | histogram | none | Player ping histogram count |