docs: add agari section to wiki, extend shanten section (#219)

* docs: add agari section to wiki, extend shanten section

* address pr feedback

* few more fixes

* few more fixes

Author: Nihisil

.github/wiki/v2-Chinese.md

@@ -152,20 +152,82 @@ print(result.yaku)
 
 ## 向听数计算
 
+向听数表示手牌到达听牌（差一张即可和牌）所需的最少换牌次数。`0` 表示听牌，`-1` 表示手牌已经和牌（完成形）。
+
+`calculate_shanten` 会计算一般形、七对子和国士无双三种形式的向听数，并返回最小值。也可以单独计算每种形式的向听数。
+
 ```python
 from mahjong.shanten import Shanten
 from mahjong.tile import TilesConverter
 
+# 一般形，2向听
 tiles = TilesConverter.string_to_34_array(man='13569', pin='123459', sou='443')
-result = Shanten.calculate_shanten(tiles)
+print("一般形向听数:", Shanten.calculate_shanten(tiles))
+
+# 听牌（0向听，差一张即可和牌）
+tiles = TilesConverter.string_to_34_array(sou='111345677', pin='11', man='567')
+print("听牌:", Shanten.calculate_shanten(tiles))
+
+# 和牌形（-1向听，已经完成）
+tiles = TilesConverter.string_to_34_array(sou='111234567', pin='11', man='567')
+print("和牌形:", Shanten.calculate_shanten(tiles))
+
+# 单独计算特定形式的向听数
+tiles = TilesConverter.string_to_34_array(sou='114477', pin='114477', man='76')
+print("七对子向听数:", Shanten.calculate_shanten_for_chiitoitsu_hand(tiles))
+
+tiles = TilesConverter.string_to_34_array(sou='129', pin='19', man='19', honors='1234567')
+print("国士无双向听数:", Shanten.calculate_shanten_for_kokushi_hand(tiles))
+```
+
+输出：
+
+```
+一般形向听数: 2
+听牌: 0
+和牌形: -1
+七对子向听数: 0
+国士无双向听数: 0
+```
+
+## 和牌判定
+
+和牌判定检查给定的手牌是否构成完成形（4面子1雀头、七对子或国士无双）。此功能仅验证牌的组合结构，不判断役种或点数。该方法比检查向听数是否为`-1`更快，因此当只需判断手牌是否完成时，建议使用`Agari.is_agari()`。
+
+```python
+from mahjong.agari import Agari
+from mahjong.tile import TilesConverter
+
+# 完成形：123s 456s 789s 123p 33m
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='123', man='33')
+print("一般形:", Agari.is_agari(tiles))
+
+# 未完成形：123s 456s 789s 12345p
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='12345')
+print("未完成形:", Agari.is_agari(tiles))
+
+# 七对子：1133557799s 1199p
+tiles = TilesConverter.string_to_34_array(sou='1133557799', pin='1199')
+print("七对子:", Agari.is_agari(tiles))
+
+# 国士无双：19s 19p 199m 1234567z
+tiles = TilesConverter.string_to_34_array(sou='19', pin='19', man='199', honors='1234567')
+print("国士无双:", Agari.is_agari(tiles))
 
-print(result)
+# 包含副露（杠子）：1111m 123456789p 22s
+tiles = TilesConverter.string_to_34_array(man='1111', pin='123456789', sou='22')
+open_set = [0, 0, 0, 0]  # 一万的杠子（34牌格式中索引为0）
+print("包含副露（杠子）:", Agari.is_agari(tiles, [open_set]))
 ```
 
 输出：
 
 ```
-2
+一般形: True
+未完成形: False
+七对子: True
+国士无双: True
+副露手（杠子）: True
 ```
 
 ## 青天井规则

.github/wiki/v2-English.md

@@ -153,20 +153,82 @@ Output:
 
 ## Shanten calculation
 
+Shanten number indicates the minimum number of tile exchanges still required for the hand to reach tenpai (one tile away from winning). A value of `0` means tenpai, and `-1` means the hand is already complete (agari).
+
+`calculate_shanten` returns the minimum shanten across regular hand, chiitoitsu (seven pairs), and kokushi (thirteen orphans) forms. You can also calculate shanten for each form individually.
+
 ```python
 from mahjong.shanten import Shanten
 from mahjong.tile import TilesConverter
 
+# regular hand, 2 shanten
 tiles = TilesConverter.string_to_34_array(man='13569', pin='123459', sou='443')
-result = Shanten.calculate_shanten(tiles)
+print("Regular hand shanten:", Shanten.calculate_shanten(tiles))
+
+# tenpai (0 shanten, one tile away from winning)
+tiles = TilesConverter.string_to_34_array(sou='111345677', pin='11', man='567')
+print("Tenpai hand:", Shanten.calculate_shanten(tiles))
+
+# complete hand (-1 shanten, already winning)
+tiles = TilesConverter.string_to_34_array(sou='111234567', pin='11', man='567')
+print("Complete hand:", Shanten.calculate_shanten(tiles))
+
+# calculate shanten for specific hand forms
+tiles = TilesConverter.string_to_34_array(sou='114477', pin='114477', man='76')
+print("Chiitoitsu shanten:", Shanten.calculate_shanten_for_chiitoitsu_hand(tiles))
+
+tiles = TilesConverter.string_to_34_array(sou='129', pin='19', man='19', honors='1234567')
+print("Kokushi shanten:", Shanten.calculate_shanten_for_kokushi_hand(tiles))
+```
+
+Output:
+
+```
+Regular hand shanten: 2
+Tenpai hand: 0
+Complete hand: -1
+Chiitoitsu shanten: 0
+Kokushi shanten: 0
+```
+
+## Agari (winning hand detection)
+
+Agari check determines whether the given tiles form a complete hand structure (4 melds + 1 pair, seven pairs, or thirteen orphans). It only validates the tile arrangement, not yaku or scoring. It is faster than checking if the shanten number is `-1`, so prefer `Agari.is_agari()` when you only need to know whether a hand is complete.
+
+```python
+from mahjong.agari import Agari
+from mahjong.tile import TilesConverter
+
+# complete hand: 123s 456s 789s 123p 33m
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='123', man='33')
+print("Regular hand:", Agari.is_agari(tiles))
+
+# incomplete hand: 123s 456s 789s 12345p
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='12345')
+print("Incomplete hand:", Agari.is_agari(tiles))
+
+# seven pairs (chiitoitsu): 1133557799s 1199p
+tiles = TilesConverter.string_to_34_array(sou='1133557799', pin='1199')
+print("Seven pairs:", Agari.is_agari(tiles))
+
+# thirteen orphans (kokushi): 19s 19p 199m 1234567z
+tiles = TilesConverter.string_to_34_array(sou='19', pin='19', man='199', honors='1234567')
+print("Kokushi:", Agari.is_agari(tiles))
 
-print(result)
+# open hand with kan meld: 1111m 123456789p 22s
+tiles = TilesConverter.string_to_34_array(man='1111', pin='123456789', sou='22')
+open_set = [0, 0, 0, 0]  # kan of 1m (tile index 0 in 34-tile format)
+print("Open hand with kan:", Agari.is_agari(tiles, [open_set]))
 ```
 
 Output:
 
 ```
-2
+Regular hand: True
+Incomplete hand: False
+Seven pairs: True
+Kokushi: True
+Open hand with kan: True
 ```
 
 ## Aotenjou scoring rules

.github/wiki/v2-Japanese.md

@@ -152,20 +152,82 @@ print(result.yaku)
 
 ## シャンテン数計算
 
+シャンテン数はテンパイ（あと1枚で和了）に到達するまでに必要な最小の牌交換回数を示します。`0` はテンパイ、`-1` は既に和了形（完成形）であることを意味します。
+
+`calculate_shanten` は一般形、七対子、国士無双の3つの形のシャンテン数を計算し、最小値を返します。各形のシャンテン数を個別に計算することもできます。
+
 ```python
 from mahjong.shanten import Shanten
 from mahjong.tile import TilesConverter
 
+# 一般形、2シャンテン
 tiles = TilesConverter.string_to_34_array(man='13569', pin='123459', sou='443')
-result = Shanten.calculate_shanten(tiles)
+print("一般形シャンテン数:", Shanten.calculate_shanten(tiles))
+
+# テンパイ（0シャンテン、あと1枚で和了）
+tiles = TilesConverter.string_to_34_array(sou='111345677', pin='11', man='567')
+print("テンパイ:", Shanten.calculate_shanten(tiles))
+
+# 和了形（-1シャンテン、既に完成）
+tiles = TilesConverter.string_to_34_array(sou='111234567', pin='11', man='567')
+print("和了形:", Shanten.calculate_shanten(tiles))
+
+# 各形のシャンテン数を個別に計算
+tiles = TilesConverter.string_to_34_array(sou='114477', pin='114477', man='76')
+print("七対子シャンテン数:", Shanten.calculate_shanten_for_chiitoitsu_hand(tiles))
+
+tiles = TilesConverter.string_to_34_array(sou='129', pin='19', man='19', honors='1234567')
+print("国士無双シャンテン数:", Shanten.calculate_shanten_for_kokushi_hand(tiles))
+```
+
+出力:
+
+```
+一般形シャンテン数: 2
+テンパイ: 0
+和了形: -1
+七対子シャンテン数: 0
+国士無双シャンテン数: 0
+```
+
+## 和了判定
+
+和了判定は、与えられた手牌が完成形（4面子1雀頭、七対子、国士無双）かどうかを判定します。牌の構成のみを検証し、役や点数の判定は行いません。シャンテン数が`-1`かどうかを確認するよりも高速なため、手牌が完成形かどうかだけを確認したい場合は`Agari.is_agari()`を使用してください。
+
+```python
+from mahjong.agari import Agari
+from mahjong.tile import TilesConverter
+
+# 完成形：123s 456s 789s 123p 33m
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='123', man='33')
+print("一般形:", Agari.is_agari(tiles))
+
+# 未完成形：123s 456s 789s 12345p
+tiles = TilesConverter.string_to_34_array(sou='123456789', pin='12345')
+print("未完成形:", Agari.is_agari(tiles))
+
+# 七対子：1133557799s 1199p
+tiles = TilesConverter.string_to_34_array(sou='1133557799', pin='1199')
+print("七対子:", Agari.is_agari(tiles))
+
+# 国士無双：19s 19p 199m 1234567z
+tiles = TilesConverter.string_to_34_array(sou='19', pin='19', man='199', honors='1234567')
+print("国士無双:", Agari.is_agari(tiles))
 
-print(result)
+# 副露あり（槓子）：1111m 123456789p 22s
+tiles = TilesConverter.string_to_34_array(man='1111', pin='123456789', sou='22')
+open_set = [0, 0, 0, 0]  # 一萬の槓子（34牌形式のインデックス0）
+print("副露あり（槓子）:", Agari.is_agari(tiles, [open_set]))
 ```
 
 出力:
 
 ```
-2
+一般形: True
+未完成形: False
+七対子: True
+国士無双: True
+副露手（槓子）: True
 ```
 
 ## 青天井ルール