From 1a326290273cc1ebe8aee54f9f5a1285a76c9efa Mon Sep 17 00:00:00 2001
From: Morteza Hosseini <s_morteza_h@yahoo.com>
Date: Mon, 3 Nov 2025 16:21:14 +0000
Subject: [PATCH] docs: update README with improved TOON description and
 installation instructions

---
 README.md | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 85fbdc2..0e0a490 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,10 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/toon-format.svg)](https://pypi.org/project/toon-format/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-**Token-Oriented Object Notation** is a compact, human-readable format designed for passing structured data to Large Language Models with significantly reduced token usage.
+**Token-Oriented Object Notation** is a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage. It's intended for LLM input, not output.
+
+> [!TIP]
+> Think of TOON as a translation layer: use JSON programmatically, convert to TOON for LLM input.
 
 ## Status
 
@@ -13,6 +16,7 @@
 ### Example
 
 **JSON** (verbose):
+
 ```json
 {
   "users": [
@@ -23,18 +27,23 @@
 ```
 
 **TOON** (compact):
-```
+
+```toon
 users[2]{id,name,role}:
   1,Alice,admin
   2,Bob,user
 ```
 
-## Resources
+## Installation
+
+Make sure [`uv`](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) is installed. Then install the `toon-format` package:
+
+```shell
+uv pip install toon-format
+# or
+uv add toon-format  # adds to your pyproject.toml
+```
 
-- [TOON Specification](https://github.com/johannschopplich/toon/blob/main/SPEC.md)
-- [Main Repository](https://github.com/johannschopplich/toon)
-- [Benchmarks & Performance](https://github.com/johannschopplich/toon#benchmarks)
-- [Other Language Implementations](https://github.com/johannschopplich/toon#other-implementations)
 
 ## Future Usage
 
@@ -43,11 +52,21 @@ Once implemented, the package will provide:
 ```python
 from toon_format import encode, decode
 
-data = # your data structure
+data = "id: 123" # your data structure
 toon_string = encode(data)
 decoded = decode(toon_string)
+
+assert data == decoded
 ```
 
+## Resources
+
+- [TOON Specification](https://github.com/johannschopplich/toon/blob/main/SPEC.md)
+- [Main Repository](https://github.com/johannschopplich/toon)
+- [Benchmarks & Performance](https://github.com/johannschopplich/toon#benchmarks)
+- [Other Language Implementations](https://github.com/johannschopplich/toon#other-implementations)
+
+
 ## Contributing
 
 Interested in implementing TOON for Python? Check out the [specification](https://github.com/johannschopplich/toon/blob/main/SPEC.md) and feel free to contribute!