docs: rewrite README with quick start, features, and usage guide; migrate setup.py to pyproject.toml with improved metadata

Author: erinshek

CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**kaalin** is a pure Python library (zero external dependencies) for Karakalpak language operations: Latin-Cyrillic script conversion, number-to-word conversion, and Karakalpak-aware string utilities. Published to PyPI as `kaalin`.
+
+## Commands
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run all tests
+python -m unittest discover test
+pytest test/
+
+# Run a single test file
+python -m unittest test.test_kaalin_converter
+pytest test/test_num2words.py
+
+# Build distribution packages
+python -m build
+
+# CLI tools (after install)
+cyr2lat input.txt [output.txt]
+lat2cyr input.txt [output.txt]
+```
+
+## Architecture
+
+The library has four modules under `kaalin/`:
+
+- **converter/** — `latin2cyrillic()` and `cyrillic2latin()` functions using dictionary-based character mapping from `constants.py`. Handles multi-character sequences (e.g., "sh" → "ш") and Cyrillic soft/hard sign rules ('ьи'→'yi', 'ьо'→'yo', 'ъе'→'ye').
+- **number/** — `to_word(number, num_type="lat")` converts integers/floats to Karakalpak words in Latin or Cyrillic script. Supports range 0 to 10^30. Raises `NumberRangeError` for out-of-range values.
+- **string/** — `upper()` and `lower()` with Karakalpak-specific character handling ('ı' ↔ 'Í').
+- **cli/** — Console script entry points (`cyr2lat`, `lat2cyr`) registered in `pyproject.toml` for file-based text conversion.
+
+Public API is re-exported from `kaalin/__init__.py`.
+
+## Code Style
+
+- 2-space indentation (per `.editorconfig`)
+- Max line length: 150 characters
+- UTF-8 encoding throughout
+- Python 3.10+ type hint syntax (`int | float`)
+
+## Release Process
+
+Version is set in `pyproject.toml` under `[project].version`. Pushing a `v*` tag triggers `.github/workflows/release.yml` which builds and publishes to PyPI via twine.
+
+## Key Constraints
+
+- No external runtime dependencies — keep it pure Python
+- CLI entry point changes must be reflected in `pyproject.toml` `[project.scripts]`
+- Tests use both `unittest` (converter, string) and `pytest` (number)

README.md

@@ -1,40 +1,107 @@
 # Kaalin
 
-<p>
-    Using this library, certain operations for the Karakalpak language can be performed very quickly and conveniently.
-</p>
+[![PyPI version](https://img.shields.io/pypi/v/kaalin)](https://pypi.org/project/kaalin/)
+[![Python](https://img.shields.io/pypi/pyversions/kaalin)](https://pypi.org/project/kaalin/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+A Python toolkit for the **Karakalpak language**: Latin-Cyrillic script conversion, number-to-words, and locale-aware string operations. Zero dependencies.
+
+## Quick Start
+
+```bash
+pip install kaalin
+```
 
-## Example
 ```python
 from kaalin.converter import latin2cyrillic, cyrillic2latin
 
+print(latin2cyrillic("Assalawma áleykum"))  # Ассалаўма әлейкум
+print(cyrillic2latin("Ассалаўма әлейкум"))  # Assalawma áleykum
+```
+
+## Supported Features
+
+| Feature | Description |
+|---|---|
+| **Script Conversion** | Bidirectional Latin ↔ Cyrillic conversion with multi-character mapping (`sh`→`ш`, `ch`→`ч`) and special Cyrillic rules (`ьи`→`yi`, `ьо`→`yo`, `ъе`→`ye`) |
+| **Number to Words** | Converts integers and floats to Karakalpak words in Latin or Cyrillic script. Supports range 0 to 10³⁰, negative numbers, and decimal fractions |
+| **String Utilities** | Karakalpak-aware `upper()` / `lower()` that correctly handle the dotless `ı` ↔ `Í` character pair |
+| **CLI Tools** | `cyr2lat` and `lat2cyr` commands for converting text files from the terminal |
 
-print(latin2cyrillic("Assalawma áleykum"))      # Ассалаўма әлейкум
-print(cyrillic2latin("Ассалаўма әлейкум"))      # Assalawma áleykum
+## API Reference
+
+### Script Conversion
+
+```python
+from kaalin.converter import latin2cyrillic, cyrillic2latin
+
+latin2cyrillic("Qaraqalpaqstan")    # Қарақалпақстан
+cyrillic2latin("Қарақалпақстан")    # Qaraqalpaqstan
 ```
 
+Both functions accept a `str` and return a `str`. The converter handles uppercase, lowercase, and mixed-case text.
+
+### Number to Words
+
 ```python
 from kaalin.number import to_word, NumberRangeError
 
-
-try:
-  print(to_word(123))                     # bir júz jigirma úsh
-  print(to_word(999, num_type="cyr"))     # тоғыз жүз тоқсан тоғыз
-  print(to_word(12.75))                   # on eki pútin júzden jetpis bes
-except NumberRangeError as e:
-  print("San shegaradan asıp ketti!")
+to_word(123)                     # bir júz jigirma úsh
+to_word(999, num_type="cyr")     # тоғыз жүз тоқсан тоғыз
+to_word(12.75)                   # on eki pútin júzden jetpis bes
+to_word(-42)                     # minus qırıq eki
 ```
 
+**Parameters:**
+- `number` (`int | float`) — the number to convert
+- `num_type` (`str`) — output script: `"lat"` (default) or `"cyr"`
+
+**Raises:** `NumberRangeError` if `number` exceeds 10³⁰.
+
+### String Utilities
+
 ```python
 from kaalin.string import upper, lower
 
-
-print(upper("Assalawma áleykum"))     # ASSALAWMA ÁLEYKUM
-print(lower("Assalawma áleykum"))     # assalawma áleykum
+upper("Assalawma áleykum")   # ASSALAWMA ÁLEYKUM
+lower("ASSALAWMA ÁLEYKUM")   # assalawma áleykum
 ```
 
-### Command Line Interface (CLI)
+Python's built-in `str.upper()` / `str.lower()` does not handle the Karakalpak dotless `ı` correctly. These functions fix that.
+
+## CLI Usage
+
+Convert text files between scripts directly from the terminal:
+
 ```bash
-$ cyr2lat input.txt [output.txt]
-$ lat2cyr input.txt [output.txt]
+# Cyrillic → Latin
+cyr2lat input.txt              # writes input-lat.txt
+cyr2lat input.txt output.txt   # writes output.txt
+
+# Latin → Cyrillic
+lat2cyr input.txt              # writes input-cyr.txt
+lat2cyr input.txt output.txt   # writes output.txt
 ```
+
+## When to Use Kaalin
+
+- Converting Karakalpak text between Latin and Cyrillic scripts
+- Displaying numbers as Karakalpak words (invoices, checks, education)
+- NLP preprocessing for Karakalpak text (script normalization)
+- Building Karakalpak-language applications that need locale-aware string operations
+- Batch-converting text files via CLI
+
+## When NOT to Use Kaalin
+
+- **Not a translator** — it converts scripts (Latin ↔ Cyrillic), not languages
+- **Not a spell-checker** — it does not validate or correct Karakalpak text
+- **Not for other Turkic languages** — Kazakh, Uzbek, Turkish, etc. have different alphabets and rules
+- **Not an OCR tool** — it works with digital text, not images
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kaalin"
+version = "3.3.1"
+description = "Karakalpak language toolkit for Python — Latin/Cyrillic script conversion, number-to-words, and string utilities"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Turdibek Jumabaev", email = "turdibekjumabaev05@gmail.com" },
+]
+keywords = [
+    "karakalpak",
+    "karakalpakstan",
+    "latin",
+    "cyrillic",
+    "transliteration",
+    "script-conversion",
+    "num2words",
+    "number-to-words",
+    "nlp",
+    "language-tools",
+    "turkic",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+[project.urls]
+Homepage = "https://github.com/dontbeidle/kaalin-python"
+Repository = "https://github.com/dontbeidle/kaalin-python"
+Issues = "https://github.com/dontbeidle/kaalin-python/issues"
+PyPI = "https://pypi.org/project/kaalin/"
+
+[project.scripts]
+cyr2lat = "kaalin.cli.converter:cyr2lat"
+lat2cyr = "kaalin.cli.converter:lat2cyr"
+
+[tool.setuptools.packages.find]
+include = ["kaalin*"]