Merge pull request #45 from SagarMaheshwary/docs/v0.7.0

docs: improve README structure, messaging, and navigation

Author: SagarMaheshwary

README.md

@@ -1,8 +1,8 @@
 # reqlog
 
 <p align="center">
-  <b>Search and trace requests across files, Docker logs, and remote hosts.</b><br/>
-  Debug distributed systems from your terminal using simple key/value search without relying on centralized tracing.
+  <b>CLI for searching, tracing, and streaming logs across files, Docker containers, and remote hosts.</b><br/>
+  Trace requests across distributed systems using request_id, trace_id, correlation_id, and key/value log search — without centralized tracing.
 </p>
 
 <p align="center">
@@ -18,46 +18,50 @@
 
 ![reqlog demo](./assets/demo.gif)
 
-## Installation
+## Table of Contents
 
-**Go Install**
+- [What is reqlog](#what-is-reqlog)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Companion UI](#companion-ui)
+- [Usage](#usage)
+- [Supported Log Formats](#supported-log-formats)
+- [What's Next](#whats-next)
 
-```bash
-go install github.com/sagarmaheshwary/reqlog/cmd/reqlog@latest
-```
+## What is reqlog?
 
-**macOS / Linux**
+reqlog is a CLI tool for searching, tracing, and streaming logs across:
 
-```bash
-curl -sSL https://raw.githubusercontent.com/sagarmaheshwary/reqlog/master/install.sh | bash
-```
+- local log files
+- Docker containers
+- remote servers over SSH
 
-- Auto-detects OS/arch
-- Installs latest version
-- Installs to `/usr/local/bin`
+It helps engineers debug requests across microservices and distributed systems using:
 
-Verify:
+- `request_id`
+- `trace_id`
+- `correlation_id`
+- custom log keys
 
-```bash
-reqlog -v
-```
+Use reqlog when logs are spread across services or hosts, centralized tracing is unavailable, or you need fast terminal-based debugging.
 
-**Windows**
+> grep for distributed systems logs
 
-Download from:
+Unlike `grep`, reqlog understands timestamps, JSON logs, Docker logs, multi-host SSH search, chronological request flow, and live log streaming.
 
-[https://github.com/sagarmaheshwary/reqlog/releases](https://github.com/sagarmaheshwary/reqlog/releases)
+## Features
 
-Then:
-
-- unzip
-- add to `PATH`
-
-Verify:
-
-```bash
-reqlog -v
-```
+- Search logs across multiple files
+- Trace requests using `request_id`, `trace_id`, and `correlation_id`
+- Stream live logs in real time (`-f`)
+- Search and stream Docker container logs
+- Search and stream logs on remote servers over SSH
+- JSON log parsing with automatic detection
+- Chronological request tracing across services
+- Context around matches (`--context`)
+- Structured JSON output for scripting
+- Time-based filtering (`--since`)
 
 ## Quick Start
 
@@ -71,6 +75,12 @@ Search log files:
 reqlog abc123
 ```
 
+Stream live logs in real time:
+
+```bash
+reqlog -f abc123
+```
+
 Search Docker containers:
 
 ```bash
@@ -93,6 +103,53 @@ Example output:
 2026-03-20T14:10:03.000Z [inventory-service] | checking stock level=info request_id=abc123
 ```
 
+## Installation
+
+**Go Install**
+
+```bash
+go install github.com/sagarmaheshwary/reqlog/cmd/reqlog@latest
+```
+
+**macOS / Linux**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/sagarmaheshwary/reqlog/master/install.sh | bash
+```
+
+- Auto-detects OS/arch
+- Installs latest version
+- Installs to `/usr/local/bin`
+
+Verify:
+
+```bash
+reqlog -v
+```
+
+**Windows**
+
+Download from:
+
+[https://github.com/sagarmaheshwary/reqlog/releases](https://github.com/sagarmaheshwary/reqlog/releases)
+
+Then:
+
+- unzip
+- add to `PATH`
+
+Verify:
+
+```bash
+reqlog -v
+```
+
+## Companion UI
+
+Visual interface for exploring reqlog results in the browser:
+
+https://github.com/sagarmaheshwary/reqlog-ui
+
 ## Usage
 
 ```bash
@@ -247,19 +304,6 @@ reqlog -f abc123
 
 > Full usage guide: [docs/usage.md](./docs/usage.md)
 
-## Why not just use `grep`?
-
-| Problem                         |      grep |      reqlog |
-| ------------------------------- | --------: | ----------: |
-| Multi-file search               | ⚠️ manual | ✅ built-in |
-| Multi-host / SSH log search     |        ❌ |          ✅ |
-| Request tracing across services |        ❌ |          ✅ |
-| JSON log search                 |        ❌ |          ✅ |
-| Chronological request flow      |        ❌ |          ✅ |
-| Service-aware context           |        ❌ |          ✅ |
-
-> `reqlog = grep for distributed systems`
-
 ## Supported Log Formats
 
 **Supported Timestamp Formats**
@@ -298,33 +342,26 @@ Timestamps are normalized to millisecond precision in output (fixed 3 digits).
 { "ts": 1710943200123, "request_id": "abc", "message": "unix milliseconds" }
 ```
 
-## Roadmap
-
-**Core Features**
+## What’s Next
 
-- [x] Flexible timestamp parsing (RFC3339 / RFC3339Nano)
-- [x] Text log parsing (key=value)
-- [x] JSON log parsing
-- [x] Wildcard support in `--service` (e.g. order-service\*)
-- [x] Unix timestamp support (logs + `--since`)
-- [x] Optimize `--limit` (early exit / streaming)
-- [x] `--latest` flag (Return latest N entries globally)
-- [x] `--context` flag (show surrounding lines)
-- [x] `--output=json` for piping and integrations
-- [ ] `--fields` flag for JSON logs
+`reqlog` now supports the core workflows it was built for:
 
-**Performance & Scalability**
+- Search local log files
+- Search Docker logs
+- Search remote logs over SSH
+- Trace requests across services using common keys like `request_id`, `trace_id`, and `correlation_id`
+- Output structured JSON for piping and automation
 
-- [ ] Parallel scanning
-- [ ] General performance improvements
+Future updates will mainly focus on:
 
-**Integrations**
+- Bug fixes and stability improvements
+- Output and usability improvements
+- Performance tuning over time
+- Additional features based on real-world usage and feedback
 
-- [x] File logs
-- [x] Docker logs
-- [x] SSH-based multi-host logs
+### Planned
 
-> Companion web UI for reqlog: https://github.com/sagarmaheshwary/reqlog-ui
+- [ ] `--fields` flag for selecting specific fields from JSON logs ([#14](https://github.com/SagarMaheshwary/reqlog/issues/14))
 
 ## Support & Contributions