docs: add badges, Try it links, and Start Here discussion template

README.md

@@ -1,7 +1,12 @@
 # RAGMap (RAG MCP Registry Finder)
 
+[![Release](https://img.shields.io/github/v/release/khalidsaidi/ragmap?display_name=tag&sort=semver)](https://github.com/khalidsaidi/ragmap/releases/latest)
+[![Deploy](https://github.com/khalidsaidi/ragmap/actions/workflows/deploy.yml/badge.svg)](https://github.com/khalidsaidi/ragmap/actions/workflows/deploy.yml)
+[![monitor-freshness](https://github.com/khalidsaidi/ragmap/actions/workflows/monitor-freshness.yml/badge.svg)](https://github.com/khalidsaidi/ragmap/actions/workflows/monitor-freshness.yml)
 [![Glama](https://glama.ai/mcp/servers/@khalidsaidi/ragmap/badge)](https://glama.ai/mcp/servers/@khalidsaidi/ragmap)
 
+**Try it:** https://ragmap-api.web.app/browse/
+
 RAGMap is a lightweight MCP Registry-compatible subregistry + MCP server focused on **RAG-related MCP servers**.
 
 It:

docs/discussions/start-here.md

@@ -0,0 +1,52 @@
+# Start here: Ragmap (What it is + how to use it)
+
+Ragmap helps you discover MCP servers, especially retrievers/RAG servers, with **reachability you can trust**.
+
+**Try it:** https://ragmap-api.web.app/browse/
+
+## What Ragmap is
+- A discovery + trust layer for MCP servers.
+- It ingests upstream registry data, enriches it for RAG use cases, and continuously probes remotes.
+- It exposes:
+
+  - `/rag/top` for smart defaults.
+  - `/rag/search` for discovery.
+  - `/rag/install` for copy/paste install configs.
+  - `/rag/stats` for freshness + coverage visibility.
+
+## The one trust concept to know
+If you want "reachable recently" results, use:
+
+- `reachable=true&reachableMaxAgeHours=24`
+
+This avoids "reachable at some unknown time" and instead means: **reachable and checked within the last N hours**.
+
+## Quickstart (copy/paste)
+### Top reachable retrievers (checked within 24h)
+
+```bash
+curl -s "https://ragmap-api.web.app/rag/top?hasRemote=true&reachable=true&reachableMaxAgeHours=24&serverKind=retriever&limit=25" | jq .
+```
+
+### Search with trust filter
+
+```bash
+curl -s "https://ragmap-api.web.app/rag/search?q=rag&hasRemote=true&reachable=true&reachableMaxAgeHours=24&limit=10" | jq .
+```
+
+### Get install config (URL-encoded name)
+
+```bash
+curl -s "https://ragmap-api.web.app/rag/install?name=ai.filegraph%2Fdocument-processing" | jq .
+```
+
+### Inspect freshness + coverage
+
+```bash
+curl -s "https://ragmap-api.web.app/rag/stats" | jq .
+```
+
+## Where to post what (so we can respond fast)
+- Bug: include the exact URL + query params you ran, and the JSON output.
+- Feature request: describe the user story ("as an agent builder...") + what success looks like.
+- New server suggestion: link to the server repo/registry entry and what category it belongs in.

docs/releases/v1.0.0.md

@@ -1,5 +1,8 @@
 # Ragmap v1.0.0 - Reachability You Can Trust
 
+**Try it:** https://ragmap-api.web.app/browse/
+
+
 Ragmap is a discovery + trust layer for MCP servers focused on retrieval/RAG. This release solidifies "reachable" as a meaningful signal, adds actionable install output, and introduces freshness-aware querying so results stay trustworthy.
 
 ## Highlights