docs: enhance README showcase

.github/workflows/quality.yml

@@ -0,0 +1,43 @@
+name: Quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Python 3.13
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install locked dependencies
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run --frozen ruff check .
+
+      - name: Check formatting
+        run: uv run --frozen ruff format --check .
+
+      - name: Type check
+        run: uv run --frozen pyright
+
+      - name: Test
+        run: uv run --frozen pytest

README.md

@@ -1,16 +1,44 @@
+<div align="center">
+
 # Defined Networking Python Client
 
-`defined-client` provides two ways to work with the
-[Defined Networking API](https://docs.defined.net/api/defined-networking-api/):
+**One client. Two interfaces. Simple automation for Defined Networking.**
+
+[![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Quality](https://github.com/rrajpuro/defined-python-client/actions/workflows/quality.yml/badge.svg)](https://github.com/rrajpuro/defined-python-client/actions/workflows/quality.yml)
+[![CLI: definedcli](https://img.shields.io/badge/CLI-definedcli-4C8BF5)](docs/cli.md)
+[![Typed: py.typed](https://img.shields.io/badge/typing-py.typed-6F42C1)](docs/python.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2EA44F)](LICENSE.md)
+
+[Quick start](#quick-start) · [Install](#install) ·
+[CLI guide](docs/cli.md) · [Python guide](docs/python.md) ·
+[API reference](https://docs.defined.net/api/defined-networking-api/)
+
+</div>
+
+---
+
+`defined-client` is a Python toolkit for the
+[Defined Networking API](https://docs.defined.net/api/defined-networking-api/).
+It combines a script-friendly CLI with a typed Python package and safer
+high-level services.
 
-- `definedcli`, a script-friendly command-line interface
-- `defined_client`, a typed Python package with low-level resources and safer
-  high-level services
+| ⚡ Script-friendly CLI | 🐍 Typed Python API | 🛡️ Safer updates |
+| :---: | :---: | :---: |
+| JSON for automation and tables for humans | Inline types and a `py.typed` marker | GET–merge–PUT helpers preserve omitted fields |
 
-The client covers hosts, roles, routes, tags, networks, audit logs, and public
-software downloads. Python 3.13 or newer is required.
+Hosts, roles, routes, tags, networks, audit logs, and public software downloads
+are supported. Python 3.13 or newer is required.
 
-## Choose an interface
+> [!NOTE]
+> This is an independent project and is not affiliated with, endorsed by, or
+> sponsored by Defined Networking.
+
+<p align="center">
+  <img src="assets/definedcli-preview.svg" alt="definedcli listing two fictional hosts in table format" width="900">
+</p>
+
+## Quick start
 
 Use the CLI for shell automation and interactive administration:
 
@@ -103,6 +131,22 @@ omitted fields.
 
 Safe updates use a GET-then-PUT sequence and can still race with another writer.
 
+<details>
+
+<summary><strong>Explore the complete CLI command tree</strong></summary>
+
+| Resource | Commands |
+| --- | --- |
+| `hosts` | `create`, `create-with-enrollment`, `list`, `get`, `get-by-name`, `find-by-name`, `update`, `replace`, `delete`, `block`, `unblock`, `debug-command`, `create-enrollment-code`, `update-tags`, `add-tag`, `remove-tag` |
+| `roles` | `create`, `list`, `get`, `update`, `replace`, `delete` |
+| `routes` | `create`, `list`, `get`, `get-by-name`, `find-by-name`, `update`, `replace`, `delete`, `update-router-host` |
+| `tags` | `create`, `list`, `get`, `find-by-key`, `update`, `replace`, `delete`, `subscribe-route`, `unsubscribe-route` |
+| `networks` | `create`, `list`, `get`, `update`, `replace` |
+| `audit-logs` | `list` |
+| `downloads` | `list` (public) |
+
+</details>
+
 ## Documentation
 
 - [CLI guide](docs/cli.md) — commands, JSON input, output, pagination, and errors

docs/development.md

@@ -40,6 +40,9 @@ Apply Ruff's safe automatic fixes and formatter while developing:
 .venv/bin/ruff format .
 ```
 
+The `Quality` GitHub Actions workflow runs the same lint, formatting, type, and
+test checks for every pull request and every push to `main`.
+
 Run one test module while iterating:
 
 ```bash