diff --git a/README.md b/README.md
index 605a076..c171dd4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,104 @@
+<p align="center">
+  <img src="assets/logo_256.png" alt="PgTidy" width="128" />
+</p>
+
 # PgTidy
 
-A PostgreSQL-focused linter and formatter for enforcing consistent SQL style, detecting PostgreSQL-specific issues, and formatting migrations, schemas, functions, procedures, triggers, and related database code.
\ No newline at end of file
+A PostgreSQL linter and formatter. Enforces consistent SQL style, detects PG-specific issues, and formats migrations, schemas, functions, procedures, and triggers.
+
+Ships as a **CLI**, **LSP server**, **VSCode extension**, and **DataGrip plugin**.
+
+---
+
+## Install
+
+```bash
+go install git.warky.dev/wdevs/pgtidy/cmd/pgtidy@latest
+```
+
+Or download a pre-built binary from [Releases](https://git.warky.dev/wdevs/pgtidy/releases).
+
+---
+
+## CLI
+
+```
+pgtidy fmt    [flags] [files...]   Format SQL/PL-pgSQL (stdin if no files)
+pgtidy lint   [flags] [files...]   Lint SQL
+pgtidy config                      Print effective configuration
+pgtidy lsp                         Start LSP server (stdio)
+pgtidy version
+```
+
+**fmt flags**
+
+| Flag | Effect |
+|------|--------|
+| `-w`, `--write` | Rewrite files in place |
+| `-l`, `--list` | List unformatted files |
+| `-d`, `--diff` | Print unified diff |
+| `--check` | Exit non-zero if not formatted (CI) |
+
+**Examples**
+
+```bash
+pgtidy fmt -w schema.sql          # format in place
+pgtidy fmt --check migrations/    # CI check
+cat query.sql | pgtidy fmt        # stdin → stdout
+pgtidy lint schema.sql            # lint a file
+```
+
+---
+
+## Config — `.pgtidy.yaml`
+
+Discovered by walking up from the target file. Defaults = house style.
+
+```yaml
+style:
+  indent: 2
+  keyword_case: upper      # upper | lower | preserve
+  identifier_case: lower
+  type_case: lower
+  leading_comma: true
+```
+
+```bash
+pgtidy config   # print resolved config
+```
+
+---
+
+## House Style (defaults)
+
+- Keywords `UPPERCASE`; data types and identifiers `lowercase`
+- 2-space indent
+- Leading-comma lists (SELECT columns, function params)
+- Function params one-per-line; `LANGUAGE`, `SECURITY`, volatility each on own line
+- PL/pgSQL: `DECLARE` block vars 2-space indented; `BEGIN`/`END` at body level
+- Spaces around binary operators (`=`, `<>`, `||`, `:=`); no space before `(` or around `::`, `->`, `->>`
+
+---
+
+## Build from Source
+
+```bash
+git clone https://git.warky.dev/wdevs/pgtidy
+cd pgtidy
+make build        # → dist/pgtidy
+make test         # all tests + corpus harness
+make snapshot     # multi-platform binaries (requires goreleaser)
+```
+
+---
+
+## Editor Integration
+
+**VSCode** — install the extension from the marketplace or build locally:
+```bash
+make vscode-package
+```
+
+**DataGrip / JetBrains** — install via the plugin marketplace (LSP4IJ-based).
+
+**Other LSP editors** — run `pgtidy lsp` as a stdio LSP server.