sashite-feen 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bcbcddcc2de55695f9a203e30fa5d3d236deaf7c0e3975011ae1a47f389cd7c
-  data.tar.gz: 98b184086642d30761cf4646dbeac1ca0a88860c11d18a15866f01e7f0b0e040
+  metadata.gz: a8182f6c48f6a615f38d75d3060f216c06c6606b118544cb4f4f0e40b9615e89
+  data.tar.gz: 1150aacab981e71aa32aaae585ec1998cd678bb5997432135b0089394eef2482
 SHA512:
-  metadata.gz: cb41ec980de1a7ae5237da821f0a3be0cabe50768cb0dceec8988465336512a0705aec6f5aa9acfe1b0cf43770996581355029be8623a19d8a44dc737c628d83
-  data.tar.gz: 95507ce051c09837ca92da2b9447b2ef3f3c9a34fdc4e412cce0ed8e32595acf91acdbae37d2ed313315db9c0e29069edae0ec1c71770b3d1f853f20896a3c0c
+  metadata.gz: b8ed4a473fce336ce73cb89c684e9ea7820842b78e12766bc32440f25da7f61998c13077ce3743972ef234a85771c63f58778835dd11bfba1fd97ef63dfb7154
+  data.tar.gz: 679296955c3b032e0ebe7b9f6ca4776b42b617f67a876e5de6bee015d186e40287d9cc964a3bb2d3faec0dbaf0dd98d810e3bf522cde197d340f168ba9be3a84

data/README.md

@@ -1,236 +1,511 @@
-Here you go — a lean, easy-to-read README that reflects the new “API / parser / dumper” design without drowning the reader in details.
+# Feen.rb
 
----
+[![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/feen.rb/main)
+![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
 
-# Feen.rb
+> **FEEN** (Forsyth–Edwards Enhanced Notation) implementation for the Ruby language.
+
+## What is FEEN?
+
+FEEN (Forsyth–Edwards Enhanced Notation) is a universal, rule-agnostic notation for representing board game positions. It extends traditional FEN to support:
+
+- **Multiple game systems** (Chess, Shōgi, Xiangqi, and more)
+- **Cross-style games** where players use different piece sets
+- **Multi-dimensional boards** (2D, 3D, and beyond)
+- **Captured pieces** (pieces-in-hand for drop mechanics)
+- **Arbitrarily large boards** with efficient empty square encoding
+- **Completely irregular structures** (any valid combination of ranks and separators)
+- **Board-less positions** (positions without piece placement, useful for pure style/turn tracking)
+
+This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/) as a pure functional library with immutable data structures.
+
+## Installation
+
+```ruby
+gem "sashite-feen"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-feen
+```
+
+## Quick Start
+
+```ruby
+require "sashite/feen"
 
-> **FEEN** — Forsyth–Edwards Enhanced Notation for rule-agnostic board positions (Chess, Shōgi-like, Xiangqi-like, variants).
+# Parse a FEEN string into an immutable position object
+position = Sashite::Feen.parse("+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c")
 
-Purely functional, immutable Ruby implementation built on top of **EPIN** (piece identifiers) and **SIN** (style identifiers).
+# Access position components
+position.placement  # Board configuration
+position.hands      # Captured pieces
+position.styles     # Game styles and active player
 
----
+# Convert placement to array based on dimensionality
+position.placement.to_a # => [[pieces...], [pieces...], ...] for 2D boards
 
-## Why FEEN?
+# Convert back to canonical FEEN string
+feen_string = Sashite::Feen.dump(position) # or position.to_s
+```
 
-* **Rule-agnostic**: expresses a board **position** without baking in game rules.
-* **Portable & canonical**: a single, deterministic string per position.
-* **Composable**: works nicely alongside other Sashité specs (e.g., STN for transitions).
+## FEEN Format
 
-FEEN strings have **three space-separated fields**:
+A FEEN string consists of three space-separated fields:
 
 ```
-<piece_placement> <pieces_in_hand> <style_turn>
+<piece-placement> <pieces-in-hand> <style-turn>
 ```
 
----
+**Example:**
+```txt
++rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c
+```
 
-## Installation
+1. **Piece placement**: Board configuration using EPIN notation with `/` separators (can be empty for board-less positions)
+2. **Pieces in hand**: Captured pieces for each player (format: `first/second`)
+3. **Style-turn**: Game styles and active player (format: `active/inactive`)
 
-Add to your `Gemfile`:
+See the [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/) for complete format details.
+
+## API Reference
+
+### Module Methods
+
+#### `Sashite::Feen.parse(string)`
+
+Parses a FEEN string into an immutable `Position` object.
+
+- **Parameter**: `string` (String) - FEEN notation string
+- **Returns**: `Position` - Immutable position object
+- **Raises**: `Sashite::Feen::Error` subclasses on invalid input
 
 ```ruby
-gem "sashite-feen"
-````
+position = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
 
-Then:
+# Board-less position (empty piece placement)
+position = Sashite::Feen.parse(" / C/c")
+```
 
-```sh
-bundle install
+#### `Sashite::Feen.dump(position)`
+
+Converts a position object into its canonical FEEN string.
+
+- **Parameter**: `position` (Position) - Position object
+- **Returns**: `String` - Canonical FEEN string
+- **Guarantees**: Deterministic output (same position always produces same string)
+
+```ruby
+feen_string = Sashite::Feen.dump(position)
 ```
 
-This gem depends on:
+### Position Object
+
+The `Position` object is immutable and provides read-only access to three components:
 
 ```ruby
-gem "sashite-epin"
-gem "sashite-sin"
+position.placement  # => Placement (board configuration)
+position.hands      # => Hands (pieces in hand)
+position.styles     # => Styles (style-turn information)
+position.to_s       # => String (canonical FEEN)
 ```
 
-Bundler will install them automatically when you use `sashite-feen`.
+**Equality and hashing:**
+```ruby
+position1 == position2  # Component-wise equality
+position1.hash          # Consistent hash for same positions
+```
 
----
+### Placement Object
 
-## Quick start
+Represents the board configuration as a flat array of ranks with explicit separators.
 
 ```ruby
-require "sashite/feen"
+placement.ranks         # => Array<Array> - Flat array of all ranks
+placement.separators    # => Array<String> - Separators between ranks (e.g., ["/", "//"])
+placement.dimension     # => Integer - Board dimensionality (1 + max consecutive slashes)
+placement.rank_count    # => Integer - Total number of ranks
+placement.one_dimensional? # => Boolean - True if dimension is 1
+placement.all_pieces    # => Array - All pieces (nils excluded)
+placement.total_squares # => Integer - Total square count
+placement.to_s          # => String - Piece placement field
+placement.to_a          # => Array - Array representation (dimension-aware)
+```
+
+#### `to_a` - Dimension-Aware Array Conversion
+
+The `to_a` method returns an array representation that adapts to the board's dimensionality:
+
+- **1D boards**: Returns a single rank array (or empty array if no ranks)
+- **2D+ boards**: Returns array of ranks
+
+```ruby
+# 1D board - Returns flat array
+feen = "K2P3k / C/c"
+position = Sashite::Feen.parse(feen)
+position.placement.to_a
+# => [K, nil, nil, P, nil, nil, nil, k]
+
+# 2D board - Returns array of arrays
+feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c"
+position = Sashite::Feen.parse(feen)
+position.placement.to_a
+# => [[r,n,b,q,k,b,n,r], [p,p,p,p,p,p,p,p], [nil×8], ...]
+
+# 3D board - Returns array of ranks (to be structured by application)
+feen = "5/5//5/5 / R/r"
+position = Sashite::Feen.parse(feen)
+position.placement.to_a
+# => [[nil×5], [nil×5], [nil×5], [nil×5]]
+
+# Empty board
+placement = Sashite::Feen::Placement.new([], [], 1)
+placement.to_a
+# => []
+```
+
+**Other methods:**
+
+```ruby
+# Access specific positions
+first_rank = placement.ranks[0]
+piece_at_a1 = first_rank[0] # Piece object or nil
+
+# Check dimensionality
+placement.dimension # => 2 (2D board)
+
+# Inspect separator structure
+placement.separators # => ["/", "/", "/", "/", "/", "/", "/"]
+```
+
+### Hands Object
+
+Represents captured pieces held by each player.
+
+```ruby
+hands.first_player   # => Array - Pieces held by first player
+hands.second_player  # => Array - Pieces held by second player
+hands.empty?         # => Boolean - True if both hands are empty
+hands.to_s           # => String - Pieces-in-hand field
+```
+
+**Example:**
+```ruby
+# Count pieces in hand
+first_player_pawns = hands.first_player.count { |p| p.to_s == "P" }
+
+# Check if any captures
+hands.empty? # => false
+```
+
+### Styles Object
 
-# Parse
-pos = Sashite::Feen.parse("<placement> <hands> <style1>/<style2>")
+Represents game styles and indicates the active player.
 
-# Validate
-Sashite::Feen.valid?("<your FEEN>") # => true/false
+```ruby
+styles.active    # => SIN identifier - Active player's style
+styles.inactive  # => SIN identifier - Inactive player's style
+styles.to_s      # => String - Style-turn field
+```
 
-# Normalize (parse → canonical dump)
-Sashite::Feen.normalize("<your FEEN>") # => canonical FEEN string
+**Example:**
+```ruby
+# Determine active player
+styles.active.to_s    # => "C" (first player Chess)
+styles.inactive.to_s  # => "c" (second player Chess)
 
-# Build from fields (strings)
-pos = Sashite::Feen.build(
-  piece_placement: "<placement>",
-  pieces_in_hand:  "<bagFirst>/<bagSecond>", # empty bags allowed: "/"
-  style_turn:      "<activeSIN>/<inactiveSIN>"
+# Check if cross-style
+styles.active.to_s.upcase != styles.inactive.to_s.upcase
+```
+
+## Examples
+
+### Chess Positions
+
+```ruby
+# Starting position
+chess_start = Sashite::Feen.parse(
+  "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
 )
 
-# Dump a Position (canonical)
-Sashite::Feen.dump(pos) # => "<placement> <hands> <style1>/<style2>"
+# After 1.e4
+after_e4 = Sashite::Feen.parse(
+  "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/4P3/8/+P+P+P+P1+P+P+P/+RNBQ+KBN+R / c/C"
+)
+
+# Ruy Lopez opening
+ruy_lopez = Sashite::Feen.parse(
+  "r1bqkbnr/+p+p+p+p1+p+p+p/2n5/1B2p3/4P3/5N2/+P+P+P+P1+P+P+P/RNBQK2R / c/C"
+)
 ```
 
-> **Tip:** FEEN itself does not do JSON; keep it minimal and functional. Serialize externally if needed.
+### Shōgi with Captured Pieces
 
----
+```ruby
+# Starting position
+shogi_start = Sashite::Feen.parse(
+  "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / S/s"
+)
+
+# Position with pieces in hand
+shogi_midgame = Sashite::Feen.parse(
+  "lnsgkgsnl/1r5b1/pppp1pppp/9/4p4/9/PPPP1PPPP/1B5R1/LNSGKGSNL P/p s/S"
+)
 
-## Public API
+# Access captured pieces
+position = shogi_midgame
+position.hands.first_player   # => [P] (one pawn)
+position.hands.second_player  # => [p] (one pawn)
+
+# Count specific pieces in hand
+position.hands.first_player.count { |p| p.to_s == "P" } # => 1
+```
+
+### Cross-Style Games
 
 ```ruby
-Sashite::Feen.parse(str)      # => Position (or raises Sashite::Feen::Error)
-Sashite::Feen.valid?(str)     # => Boolean
-Sashite::Feen.dump(position)  # => String (canonical)
-Sashite::Feen.normalize(str)  # => String (dump(parse(str)))
-Sashite::Feen.build(
-  piece_placement:, pieces_in_hand:, style_turn:
-)                             # => Position
+# Chess vs Makruk
+chess_vs_makruk = Sashite::Feen.parse(
+  "rnsmksnr/8/pppppppp/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/m"
+)
+
+# Chess vs Shōgi
+chess_vs_shogi = Sashite::Feen.parse(
+  "lnsgkgsnl/1r5b1/pppppppp/9/9/9/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/s"
+)
+
+# Check styles
+position = chess_vs_makruk
+position.styles.active.to_s    # => "C" (Chess, first player)
+position.styles.inactive.to_s  # => "m" (Makruk, second player)
 ```
 
-Position value-objects are immutable:
+### Multi-Dimensional Boards
 
 ```ruby
-pos.placement  # => Sashite::Feen::Placement
-pos.hands      # => Sashite::Feen::Hands
-pos.styles     # => Sashite::Feen::Styles
-pos.to_s       # => canonical FEEN string (same as dump(pos))
+# 3D Chess (Raumschach)
+raumschach = Sashite::Feen.parse(
+  "rnknr/+p+p+p+p+p/5/5/5//buqbu/+p+p+p+p+p/5/5/5//5/5/5/5/5//5/5/5/+P+P+P+P+P/BUQBU//5/5/5/+P+P+P+P+P/RNKNR / R/r"
+)
+
+# Check dimensionality
+raumschach.placement.dimension  # => 3 (3D board)
+raumschach.placement.ranks.size # => 25 (total ranks)
+
+# Inspect separator structure
+level_seps = raumschach.placement.separators.count { |s| s == "//" }
+rank_seps = raumschach.placement.separators.count { |s| s == "/" }
+# level_seps => 4 (separates 5 levels)
+# rank_seps => 20 (separates ranks within levels)
 ```
 
----
+### Irregular Boards
 
-## Canonicalization (short rules)
+```ruby
+# Diamond-shaped board
+diamond = Sashite::Feen.parse("3/4/5/4/3 / G/g")
 
-* **Piece placement (field 1)**
+# Check structure
+diamond.placement.ranks.map(&:size) # => [3, 4, 5, 4, 3]
 
-  * Consecutive empties compress to digits `1..9`; runs `>9` are split into `"9"` + remainder.
-  * Digit `0` in empties is invalid.
-  * EPIN tokens are validated via `sashite-epin` and re-emitted canonically.
+# Very large board
+large_board = Sashite::Feen.parse("100/100/100 / G/g")
+large_board.placement.total_squares # => 300
 
-* **Pieces in hand (field 2)**
+# Single square
+single = Sashite::Feen.parse("K / C/c")
+single.placement.rank_count # => 1
+```
+
+### Completely Irregular Structures
 
-  * Two concatenated bags separated by `/` (either side may be empty).
-  * Counts are aggregated; `1` is omitted in output.
-  * Deterministic sort per EPIN: quantity ↓, letter ↑ (case-insensitive), uppercase before lowercase, prefix `-` < `+` < none, suffix none < `'`.
+FEEN supports any valid combination of ranks and separators:
+
+```ruby
+# Extreme irregularity with variable separators
+feen = "99999/3///K/k//r / G/g"
+position = Sashite::Feen.parse(feen)
+
+# Access the structure
+position.placement.ranks.size      # => 5 ranks
+position.placement.separators      # => ["/", "///", "/", "//"]
+position.placement.dimension       # => 4 (max separator is "///")
+
+# Each rank can have different sizes
+position.placement.ranks[0].size   # => 99999
+position.placement.ranks[1].size   # => 3
+position.placement.ranks[2].size   # => 1
+position.placement.ranks[3].size   # => 1
+position.placement.ranks[4].size   # => 1
+
+# Round-trip preservation
+Sashite::Feen.dump(position) == feen # => true
+```
 
-* **Style-turn (field 3)**
+### Empty Ranks
 
-  * Exactly two SIN tokens separated by `/`.
-  * Exactly **one uppercase** style (first player) and **one lowercase** style (second).
-  * The **first token is the active** player’s style.
+FEEN supports empty ranks (ranks with no pieces):
 
----
+```ruby
+# Trailing separator creates empty rank
+feen = "K/// / C/c"
+position = Sashite::Feen.parse(feen)
 
-## Design overview
+position.placement.ranks.size  # => 2
+position.placement.ranks[0]    # => [K]
+position.placement.ranks[1]    # => [] (empty rank)
+position.placement.separators  # => ["///"]
 
-The gem is small, layered, and testable:
+# Round-trip preserves structure
+Sashite::Feen.dump(position) == feen # => true
+```
 
-* **API**: `Sashite::Feen` (parse / valid? / dump / normalize / build)
-* **Value objects**: `Position`, `Placement`, `Hands`, `Styles` (immutable, canonical)
-* **Parser**: `Feen::Parser` orchestrates field parsers (`Parser::PiecePlacement`, `Parser::PiecesInHand`, `Parser::StyleTurn`)
-* **Dumper**: `Feen::Dumper` orchestrates field dumpers (`Dumper::PiecePlacement`, `Dumper::PiecesInHand`, `Dumper::StyleTurn`)
-* **Ordering**: `Feen::Ordering` — single comparator used by the hands dumper
-* **Errors**: `Feen::Error` (see below)
+### Board-less Positions
 
-### Project layout
+FEEN supports positions without piece placement, useful for tracking only style and turn information:
 
+```ruby
+# Position with empty board (no piece placement)
+board_less = Sashite::Feen.parse(" / C/c")
+
+board_less.placement.ranks.size     # => 1
+board_less.placement.dimension      # => 1
+board_less.placement.to_a           # => []
+
+# Convert back to FEEN
+Sashite::Feen.dump(board_less) # => " / C/c"
 ```
-lib/
-├─ sashite-feen.rb
-└─ sashite/
-   ├─ feen.rb                 # Public API
-   └─ feen/
-      ├─ error.rb
-      ├─ position.rb
-      ├─ placement.rb
-      ├─ hands.rb
-      ├─ styles.rb
-      ├─ ordering.rb
-      ├─ parser.rb
-      ├─ parser/
-      │  ├─ piece_placement.rb
-      │  ├─ pieces_in_hand.rb
-      │  └─ style_turn.rb
-      ├─ dumper.rb
-      └─ dumper/
-         ├─ piece_placement.rb
-         ├─ pieces_in_hand.rb
-         └─ style_turn.rb
+
+### Working with Positions
+
+```ruby
+# Compare positions
+position1 = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
+position2 = Sashite::Feen.parse("8/8/8/8/8/8/8/8 / C/c")
+position1 == position2 # => true
+
+# Round-trip parsing
+original = "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
+position = Sashite::Feen.parse(original)
+Sashite::Feen.dump(position) == original # => true
+
+# Extract specific information
+position.placement.ranks[0] # First rank (array of pieces/nils)
+position.hands.first_player.size # Number of captured pieces
 ```
 
-> Version is defined outside of `lib/sashite/feen/version.rb` (e.g., `VERSION.semver`).
+### State Modifiers and Derivation
 
----
+```ruby
+# Enhanced pieces (promoted, with special rights)
+enhanced = Sashite::Feen.parse("+K+Q+R+B/8/8/8/8/8/8/8 / C/c")
 
-## Errors
+# Diminished pieces (weakened, vulnerable)
+diminished = Sashite::Feen.parse("-K-Q-R-B/8/8/8/8/8/8/8 / C/c")
 
-Rescue at the granularity you need:
+# Foreign pieces (using opponent's style)
+foreign = Sashite::Feen.parse("K'Q'R'B'/k'q'r'b'/8/8/8/8/8/8 / C/s")
+```
 
-* `Sashite::Feen::Error::Syntax` – tokenization/field arity
-* `Sashite::Feen::Error::Piece`  – EPIN validation failures
-* `Sashite::Feen::Error::Style`  – SIN validation/case issues
-* `Sashite::Feen::Error::Count`  – invalid counts in hands
-* `Sashite::Feen::Error::Bounds` – internal dimension constraints (when relevant)
-* `Sashite::Feen::Error::Validation` – generic structural/semantic errors
+## Error Handling
 
-Example:
+FEEN defines specific error classes for different validation failures:
 
 ```ruby
 begin
-  pos = Sashite::Feen.parse(str)
-rescue Sashite::Feen::Error::Style => e
-  warn "Bad style-turn: #{e.message}"
+  position = Sashite::Feen.parse("invalid feen")
+rescue Sashite::Feen::Error => e
+  # Base error class catches all FEEN errors
+  warn "FEEN error: #{e.message}"
 end
 ```
 
----
+### Error Hierarchy
 
-## Dependencies & compatibility
+```txt
+Sashite::Feen::Error             # Base error class
+├── Error::Syntax                # Malformed FEEN structure
+├── Error::Piece                 # Invalid EPIN notation
+├── Error::Style                 # Invalid SIN notation
+├── Error::Count                 # Invalid piece counts
+└── Error::Validation            # Other semantic violations
+```
+
+### Common Errors
+
+```ruby
+# Syntax error - wrong field count
+Sashite::Feen.parse("8/8/8/8/8/8/8/8 /")
+# => Error::Syntax: "FEEN must have exactly 3 space-separated fields, got 2"
+
+# Style error - invalid SIN
+Sashite::Feen.parse("8/8/8/8/8/8/8/8 / 1/2")
+# => Error::Style: "failed to parse SIN '1': invalid SIN notation: '1' (must be a single letter A-Z or a-z)"
+
+# Count error - invalid quantity
+Sashite::Feen.parse("8/8/8/8/8/8/8/8 0P/ C/c")
+# => Error::Count: "piece count must be at least 1, got 0"
+```
 
-* Runtime: `sashite-epin`, `sashite-sin`
-* Purely functional; all objects are frozen; methods return new values.
-* No JSON serialization in this gem.
+## Properties
 
----
+- **Purely functional**: Immutable data structures, no side effects
+- **Canonical output**: Deterministic string generation (same position → same string)
+- **Specification compliant**: Strict adherence to [FEEN v1.0.0](https://sashite.dev/specs/feen/1.0.0/)
+- **Minimal API**: Two methods (`parse` and `dump`) for complete functionality
+- **Universal**: Supports any abstract strategy board game
+- **Completely flexible**: Accepts any valid combination of ranks and separators
+- **Perfect round-trip**: `parse(dump(position)) == position` guaranteed
+- **Dimension-aware**: Intelligent array conversion based on board structure
+- **Composable**: Built on [EPIN](https://github.com/sashite/epin.rb) and [SIN](https://github.com/sashite/sin.rb) specifications
+
+## Dependencies
+
+- [sashite-epin](https://github.com/sashite/epin.rb) — Extended Piece Identifier Notation
+- [sashite-sin](https://github.com/sashite/sin.rb) — Style Identifier Notation
+
+## Documentation
+
+- [FEEN Specification v1.0.0](https://sashite.dev/specs/feen/1.0.0/) — Complete technical specification
+- [FEEN Examples](https://sashite.dev/specs/feen/1.0.0/examples/) — Comprehensive examples
+- [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main) — Full API reference
+- [GitHub Wiki](https://github.com/sashite/feen.rb/wiki) — Advanced usage and patterns
 
 ## Development
 
 ```sh
-# Clone
+# Clone the repository
 git clone https://github.com/sashite/feen.rb.git
 cd feen.rb
 
-# Install
+# Install dependencies
 bundle install
 
-# Run smoke tests
+# Run tests
 ruby test.rb
 
-# Generate YARD docs
+# Generate documentation
 yard doc
 ```
 
----
-
 ## Contributing
 
 1. Fork the repository
-2. Create a feature branch: `git checkout -b feat/my-change`
-3. Add tests covering your changes
-4. Ensure everything is green (lint, tests, docs)
-5. Commit with a conventional message
-6. Push and open a Pull Request
-
----
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`ruby test.rb`)
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Create a Pull Request
 
 ## License
 
-Open source under the [MIT License](https://opensource.org/licenses/MIT).
-
----
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About
 
-Maintained by **Sashité** — promoting chess variants and sharing the beauty of board-game cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.