From 89763f77f181c948f0b03f2b8a38e39732c5039d Mon Sep 17 00:00:00 2001
From: Marcin Wojas <marcin.wojas@enova.pl>
Date: Fri, 26 Dec 2025 22:16:00 +0100
Subject: [PATCH] Revise README for Soneta ORM AI Skills

Updated README to enhance project clarity and structure.
---
 README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 151 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 662a58f..69c7fbf 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,151 @@
-# AiSkillsForSoneta
-Zestaw skills dla asystentów AI (Claude, Cursor, Windsurf, itp.) wspierających programowanie z ORM platformy enova365/Soneta Enterprise.
+# Soneta ORM AI Skills
+
+Zestaw skills dla asystentów AI (Claude, Cursor, Windsurf, itp.) wspierających programowanie z ORM platformy **enova365/Soneta Enterprise**.
+
+## 🎯 Cel projektu
+
+Skille zawierają dokumentację i wzorce programistyczne, które pozwalają asystentom AI efektywnie pomagać w tworzeniu dodatków dla systemu enova365. Dzięki nim AI rozumie specyfikę platformy Soneta: mapowanie obiektowo-relacyjne, strukturę modułów, zarządzanie sesjami i transakcjami.
+
+## 📦 Dostępne skille
+
+### 1. soneta-programming-basics
+
+Fundamentalne klasy ORM platformy enova365/Soneta Enterprise.
+
+**Zakres:**
+- Mapowanie obiektowo-relacyjne (`Row`, `Table`, `Module`)
+- Zarządzanie sesją (`Session`) i transakcjami biznesowymi
+- Logowanie i dostęp do bazy (`Login`, `Database`, `BusApplication`)
+- Paczki danych (`Datapack`, `GuidedRow`) i synchronizacja
+- Kontekst aplikacji (`Context`)
+
+**Kiedy używać:**
+- Pytania o podstawowe klasy logiki biznesowej
+- Praca z sesjami i transakcjami
+- Tworzenie, modyfikacja i usuwanie obiektów
+- Zrozumienie hierarchii `Row` → `Table` → `Module`
+
+### 2. enova365-business-xml
+
+Generator plików `business.xml` definiujących strukturę obiektów biznesowych.
+
+**Zakres:**
+- Definiowanie tabel i kolumn
+- Typy danych (proste, relacyjne, złożone)
+- Relacje między obiektami (1:N, N:1, polimorficzne)
+- Klucze i indeksy
+- Wzorce: słowniki, dokumenty z pozycjami, historia zmian
+
+**Kiedy używać:**
+- Tworzenie nowego modułu biznesowego
+- Definiowanie encji do przechowywania w bazie
+- Tworzenie relacji między obiektami
+- Generowanie plików `*.business.xml`
+
+## 🚀 Instalacja
+
+### Claude Desktop / Claude.ai
+
+Skopiuj folder ze skillem do katalogu skills w konfiguracji Claude.
+
+### Cursor / Windsurf / inne IDE
+
+Dodaj zawartość skilli do kontekstu projektu lub rules.
+
+## 📁 Struktura repozytorium
+
+```
+soneta-ai-skills/
+├── README.md
+├── soneta-programming-basics/
+│   ├── SKILL.md                    # Główna dokumentacja
+│   └── references/
+│       ├── session-login.md        # BusApplication, Database, Login, Session
+│       ├── datapack-guidedrow.md   # Paczki danych, GuidedRow, synchronizacja
+│       ├── context.md              # Klasa Context, komunikacja UI ↔ logika
+│       └── examples.md             # Przykłady kodu i wzorce użycia
+│
+└── enova365-business-xml/
+    ├── SKILL.md                    # Główna dokumentacja
+    ├── assets/
+    │   └── business_struct.xsd     # Schemat XSD dla walidacji
+    └── references/
+        ├── modules-catalog.md      # Katalog modułów enova365
+        ├── table-reference.md      # Dokumentacja atrybutów table i col
+        ├── relations-guide.md      # Tworzenie relacji między obiektami
+        └── examples.md             # Przykłady z rzeczywistych modułów
+```
+
+## 💡 Przykłady użycia
+
+### Tworzenie nowego obiektu
+
+```csharp
+using (var session = login.CreateSession(false, false, "Dodawanie"))
+{
+    var tm = session.GetTowary();
+    
+    using (var transaction = session.Logout(editMode: true))
+    {
+        var towar = new Towar();
+        tm.Towary.AddRow(towar);
+        towar.Kod = "NOWY001";
+        towar.Nazwa = "Nowy towar";
+        transaction.Commit();
+    }
+    
+    session.Save();
+}
+```
+
+### Definicja obiektu w business.xml
+
+```xml
+<table name="Towar" tablename="Towary" guided="Root" 
+       caption="Towar" tablecaption="Towary">
+  <key name="WgKodu" keyunique="true" keyprimary="true">
+    <keycol name="Kod"/>
+  </key>
+  <col name="Kod" type="string" length="100" required="true"/>
+  <col name="Nazwa" type="string" length="200" required="true"/>
+  <col name="Cena" type="currency"/>
+</table>
+```
+
+## 🔗 Powiązania między skillami
+
+Skille są zaprojektowane do współpracy:
+
+1. **enova365-business-xml** → definiuje strukturę obiektów
+2. **soneta-programming-basics** → pokazuje jak pracować z wygenerowanymi klasami
+
+Generator `BusinessGenerator` automatycznie tworzy klasy C# z plików `*.business.xml` podczas kompilacji projektu.
+
+## 📝 Konwencje nazewnicze
+
+| Element | Konwencja | Przykład |
+|---------|-----------|----------|
+| Klasa wiersza | PascalCase, l.poj. | `Towar`, `Kontrahent` |
+| Klasa tabeli | PascalCase, l.mn. | `Towary`, `Kontrahenci` |
+| Klasa modułu | Nazwa + Module | `TowaryModule` |
+| Klucz | Wg + nazwa kolumny | `WgKodu`, `WgNazwy` |
+| Namespace | Soneta.NazwaModułu | `Soneta.Towary` |
+
+Obiekty biznesowe (domenowe) nazywane są po polsku: `Towar`, `Faktura`, `Kontrahent`.
+Obiekty systemowe (techniczne) po angielsku: `Session`, `Context`, `Row`.
+
+## 🤝 Współpraca
+
+Zapraszamy do zgłaszania issues i pull requestów. Szczególnie cenne są:
+- Nowe przykłady kodu
+- Poprawki w dokumentacji
+- Dodatkowe wzorce programistyczne
+
+## 📄 Licencja
+
+MIT
+
+## 🔗 Linki
+
+- [Dokumentacja enova365](https://www.enova.pl/)
+- [Soneta Developer Portal](https://developer.enova365.pl/)