docs: modern README, MIT LICENSE, correct project URLs

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ArthurC-Nina

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Chenais
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,137 +1,167 @@
-# netcup-api · `netcup` CLI
+<div align="center">
 
-A solid, spec-driven Python client **library** and **command-line interface** for the
-[netcup Server Control Panel (SCP) REST API](https://www.netcup.com/en/helpcenter/documentation/server/rest-api).
+# 🚀 netcup-api
 
-> The legacy SOAP webservice was shut down on **2026-05-01**. This tool targets the
-> modern REST API (`scp-core`, OAuth2 / Keycloak device flow).
+### A modern, spec-driven Python client & CLI for the netcup Server Control Panel (SCP) REST API
 
-## Why this design
+[![CI](https://github.com/fullya99/netcup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/fullya99/netcup-cli/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#-license)
+[![Built on OpenAPI](https://img.shields.io/badge/driven%20by-OpenAPI-6BA539.svg?logo=openapiinitiative&logoColor=white)](https://www.servercontrolpanel.de/scp-core/api/v1/openapi)
 
-Everything is driven by the API's own **OpenAPI specification**, which is bundled and
-can be refreshed at any time (`netcup spec update`). This means:
+*Manage your netcup VPS fleet from the terminal — power, snapshots, firewall, rDNS, metrics — with **every** API endpoint one command away.*
 
-- **All endpoints are covered** — not just the hand-written convenience commands.
-  `netcup endpoints` lists them; `netcup call <operationId>` invokes any of them.
-- **Future-proof** — when netcup adds or changes endpoints, refresh the spec and the
-  new operations are immediately available via `endpoints` / `call`, with no code change.
-- **No hard-coded hostnames or guessing** — the auth flow and base URLs are explicit and
-  documented in `netcup_api/config.py`.
+[Install](#-install) · [Authenticate](#-authenticate-once) · [Commands](#-everyday-commands) · [Any endpoint](#-reach-any-endpoint) · [Library](#-use-as-a-library)
 
-## Install
+</div>
+
+---
+
+> [!NOTE]
+> netcup's legacy SOAP webservice was shut down on **2026‑05‑01**. This tool targets the modern
+> **REST API** (`scp-core`) with OAuth2 / Keycloak device‑flow auth.
+
+## ✨ Why this one
+
+|  | |
+|---|---|
+| 🧭 **Spec-driven** | Every command is backed by the API's own OpenAPI spec — no hand-maintained endpoint lists. |
+| 🔌 **All endpoints, always** | Curated commands for daily ops **+** a generic layer (`call` / `api`) that reaches *all* operations. |
+| 🔮 **Future-proof** | New netcup endpoint? `netcup spec update` and it's instantly usable — zero code changes. |
+| 🔐 **Secure by default** | Only the offline refresh token is stored (mode `0600`); the 300 s access token is cached & auto-refreshed. |
+| 🎨 **Pretty output** | Rich tables with humanized sizes, or `--json` for clean `jq` piping. |
+| 🤝 **Shared core** | Same engine powers the [`netcup-mcp`](https://github.com/fullya99/netcup-mcp) server. |
+
+## 📦 Install
 
 ```bash
 pip install netcup-api          # from PyPI (once published)
-# or, from source:
+# or from source:
+git clone https://github.com/fullya99/netcup-cli && cd netcup-cli
 pip install -e .
 ```
 
-## Authenticate (once)
+## 🔑 Authenticate (once)
 
 Authentication uses the OAuth2 **device-code flow** against netcup's Keycloak realm.
-Only the long-lived *offline refresh token* is stored (`~/.config/netcup-api/credentials.json`, mode 0600);
-the 300-second access token is cached separately and refreshed automatically.
 
 ```bash
-netcup auth login          # prints a URL + user code, opens your browser
-netcup auth status         # show who you are (incl. SCP userId)
-netcup auth logout         # revoke the refresh token and wipe local creds
+netcup auth login          # prints a URL + code, opens your browser
+netcup auth status         # who am I? (incl. SCP userId)
+netcup auth logout         # revoke the refresh token & wipe local creds
 ```
 
-> The offline refresh token stays valid **as long as it is used at least once every 30 days**.
-> If unused longer, re-run `netcup auth login`.
+> [!TIP]
+> The offline refresh token stays valid **as long as it's used at least once every 30 days**.
+> Only the refresh token is persisted (`~/.config/netcup-api/`, `0600`); the access token is cached and refreshed automatically.
 
-## Daily-driver commands
+## ⚡ Everyday commands
 
 ```bash
+# Servers
 netcup servers list                         # table of your servers
 netcup servers get <serverId>
 netcup servers start <serverId>             # power ON
 netcup servers stop  <serverId>             # power OFF
-netcup servers set-hostname <serverId> host.example.com
+netcup servers set-hostname <serverId> web01.example.com
 
-netcup snapshots list <serverId>
+# Snapshots
 netcup snapshots create <serverId> before-upgrade --online
 netcup snapshots revert <serverId> before-upgrade
-netcup snapshots delete <serverId> before-upgrade
+netcup snapshots list   <serverId>
 
+# Networking
 netcup rdns set 203.0.113.10 host.example.com
-netcup rdns set 2a03:... host.example.com --v6
+netcup rdns set 2a03:4000:: host.example.com --v6
+netcup interfaces <serverId>
 
-netcup ssh-keys list
+# Keys, firewall, disks, ISO/images, metrics, tasks
 netcup ssh-keys add laptop --key-file ~/.ssh/id_ed25519.pub
-
 netcup firewall policies
+netcup disks <serverId>
+netcup iso list   /   netcup iso available <serverId>
+netcup images list
+netcup metrics <serverId> cpu               # cpu | disk | network | network/packet
 netcup tasks list
-netcup metrics <serverId> cpu
-netcup interfaces <serverId>
-
-netcup disks <serverId>                     # disk table (sizes humanized)
-netcup images list                          # your uploaded custom images
-netcup images flavours <serverId>           # available install flavours
-netcup iso list                             # your uploaded ISOs
-netcup iso attached <serverId>              # ISO currently attached
-netcup iso available <serverId>             # ISO images available to attach
 ```
 
-Add `--json` / `-j` to any command for raw JSON output (great for scripting with `jq`).
+Add `--json` / `-j` to **any** command for raw JSON (great with `jq`).
+
+## 🌐 Reach *any* endpoint
 
-## Reach *any* endpoint (spec-driven)
+The CLI is OpenAPI-driven, so the full API is one command away — even endpoints with no curated wrapper:
 
 ```bash
-netcup endpoints                 # list all endpoints
-netcup endpoints snapshot        # filter
+netcup endpoints                 # list every endpoint
+netcup endpoints snapshot        # filter by text
 netcup endpoints --tag "Server Networking"
-netcup describe get-servers-by-serverId      # params + request schema
+netcup describe get-servers-by-serverId       # params + request body schema
 
-# Invoke any operation by id; path params via -p, query via -q, body via -d/--data-file/--stdin.
-# (userId is auto-filled from your identity.)
+# Invoke any operation by id (userId is auto-filled). Path via -p, query via -q, body via -d.
 netcup call get-servers -q limit=10
 netcup call patch-servers-by-serverId -p serverId=12345 -d '{"state":"ON"}'
-netcup call post-rdns-ipv4 -d '{"ip":"203.0.113.10","rdns":"host.example.com"}'
 
 # Or the raw escape hatch:
-netcup api GET /api/v1/servers -q q=web
+netcup api GET   /api/v1/servers -q q=web
 netcup api PATCH /api/v1/servers/12345 -d '{"hostname":"web01"}'
 ```
 
-## Keep the spec current
+Keep the spec current:
 
 ```bash
 netcup spec info       # bundled spec version + endpoint/tag count
-netcup spec update     # download the latest spec from the live API
+netcup spec update     # pull the latest spec from the live API
 ```
 
-## Use as a library
+## 🐍 Use as a library
 
 ```python
 from netcup_api import NetcupClient
 
-c = NetcupClient()                      # uses your stored credentials
-servers = c.list_servers(limit=10)
+c = NetcupClient()                       # uses your stored credentials
+for s in c.list_servers(limit=10):
+    print(s["name"], s["state"])
+
 c.set_server_state("12345", "ON")
 c.call("post-servers-by-serverId-snapshots",
        path_params={"serverId": "12345"},
        body={"name": "snap1", "onlineSnapshot": True})
 ```
 
-## Known limits & gotchas (from the API)
+## ⚠️ Good to know
 
 | Topic | Detail |
 |------|--------|
-| Access token | valid **300 s**; auto-refreshed by this client |
-| Refresh token | offline; dies after **30 days unused** → re-login |
-| `PATCH /servers/{id}` | **one attribute per request** (else HTTP 400); `Content-Type: application/merge-patch+json` (handled automatically) |
-| Image/ISO uploads | the API returns presigned S3 URLs; the binary upload itself is a separate `PUT` to that URL (not yet wrapped — use the returned URL directly) |
+| Access token | valid **300 s** — refreshed automatically by the client |
+| Refresh token | offline; dies after **30 days unused** → re-run `netcup auth login` |
+| `PATCH /servers/{id}` | **one attribute per request** (else HTTP 400); `Content-Type: application/merge-patch+json` (handled for you) |
+| Image/ISO uploads | the API returns presigned S3 URLs; the binary `PUT` to that URL is a separate step |
 
-## Configuration (env vars)
+## 🔧 Configuration
 
-| Var | Default |
-|-----|---------|
+| Env var | Default |
+|---------|---------|
 | `NETCUP_CONFIG_DIR` | `~/.config/netcup-api` |
 | `NETCUP_BASE_HOST` | `https://www.servercontrolpanel.de` |
 | `NETCUP_OPENAPI` | path to an explicit spec file (overrides bundled/cached) |
 
-## License
+## 🛠️ Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .          # lint
+pytest -q             # offline tests (no network, no auth)
+```
+
+See [`CLAUDE.md`](./CLAUDE.md) for architecture, the spec-driven principle, and contribution rules.
+
+## 🤖 AI assistant integration
+
+Want Claude / any MCP client to drive your infra in natural language? Pair this with the
+companion MCP server: **[netcup-mcp](https://github.com/fullya99/netcup-mcp)**.
+
+## 📄 License
+
+[MIT](https://opensource.org/licenses/MIT) © Antoine Chenais
 
-MIT
+<div align="center"><sub>Not affiliated with netcup GmbH. Use at your own risk on production infrastructure.</sub></div>

pyproject.toml

@@ -24,8 +24,8 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/achenais/netcup-cli"
-Issues = "https://github.com/achenais/netcup-cli/issues"
+Homepage = "https://github.com/fullya99/netcup-cli"
+Issues = "https://github.com/fullya99/netcup-cli/issues"
 
 [project.scripts]
 netcup = "netcup_api.cli:main"