sashite-pan 2.0.0 → 4.0.0

data/README.md

@@ -5,20 +5,13 @@
 ![Ruby](https://github.com/sashite/pan.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/pan.rb?label=License&logo=github)](https://github.com/sashite/pan.rb/raw/main/LICENSE.md)
 
-> **PAN** (Portable Action Notation) support for the Ruby language.
+> **PAN** (Portable Action Notation) implementation for the Ruby language.
 
 ## What is PAN?
 
-PAN (Portable Action Notation) is a compact, string-based format for representing **executed moves** in abstract strategy board games. PAN serves as a human-readable and space-efficient alternative to PMN (Portable Move Notation), expressing the same semantic information in a condensed textual format.
+PAN (Portable Action Notation) is a human-readable string format for representing atomic actions in abstract strategy board games. PAN provides an intuitive operator-based syntax to describe how pieces move, capture, transform, and interact on game boards.
 
-While PMN uses JSON arrays to describe move sequences, PAN encodes the same information using a delimited string format that is easier to read, write, and transmit in contexts where JSON overhead is undesirable.
-
-This gem implements the [PAN Specification v1.0.0](https://sashite.dev/documents/pan/1.0.0/), providing a Ruby interface for:
-
-- Converting between PAN strings and PMN format
-- Parsing PAN strings into structured move data
-- Creating PAN strings from move components
-- Validating PAN strings according to the specification
+This gem implements the [PAN Specification v1.0.0](https://sashite.dev/specs/pan/1.0.0/), providing a pure functional Ruby interface with immutable action objects.
 
 ## Installation
 
@@ -33,264 +26,607 @@ Or install manually:
 gem install sashite-pan
 ```
 
-## PAN Format
+## Quick Start
+
+```ruby
+require "sashite/pan"
+
+# Validate PAN strings
+Sashite::Pan.valid?("e2-e4")      # => true
+Sashite::Pan.valid?("d1+f3")      # => true
+Sashite::Pan.valid?("...")        # => true
+Sashite::Pan.valid?("invalid")    # => false
+
+# Parse PAN strings into action objects
+action = Sashite::Pan.parse("e2-e4")
+action.type          # => :move
+action.source        # => "e2"
+action.destination   # => "e4"
+action.to_s          # => "e2-e4"
+
+# Create actions programmatically
+action = Sashite::Pan::Action.move("e2", "e4")
+action.to_s          # => "e2-e4"
+
+promotion = Sashite::Pan::Action.move("e7", "e8", transformation: "Q")
+promotion.to_s       # => "e7-e8=Q"
+
+capture = Sashite::Pan::Action.capture("d1", "f3")
+capture.to_s         # => "d1+f3"
+
+# Drop actions (shogi-style)
+drop = Sashite::Pan::Action.drop("e5", piece: "P")
+drop.to_s            # => "P*e5"
+
+# Pass action
+pass = Sashite::Pan::Action.pass
+pass.to_s            # => "..."
+
+# Query action properties
+action.move?         # => true
+action.pass?         # => false
+capture.capture?     # => true
+```
+
+## Format Overview
+
+PAN uses six intuitive operators:
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `-` | Move to empty square | `e2-e4` |
+| `+` | Capture at destination | `d1+f3` |
+| `~` | Special move with side effects | `e1~g1` (castling) |
+| `*` | Drop to empty square | `P*e5` |
+| `.` | Drop with capture | `L.b4` |
+| `=` | Transform piece | `e4=+P` |
+| `...` | Pass turn | `...` |
+
+For complete format details, see the [PAN Specification](https://sashite.dev/specs/pan/1.0.0/).
+
+## API Reference
+
+### Module Methods
+
+#### Validation
+
+```ruby
+Sashite::Pan.valid?(pan_string)
+```
+
+Check if a string represents a valid PAN action.
+
+**Parameters:**
+- `pan_string` [String] - The string to validate
+
+**Returns:** [Boolean] - true if valid PAN, false otherwise
 
-A PAN string represents one or more **actions** that constitute a complete move in a game. The format structure is:
+**Examples:**
+```ruby
+Sashite::Pan.valid?("e2-e4")       # => true
+Sashite::Pan.valid?("P*d4")        # => true
+Sashite::Pan.valid?("...")         # => true
+Sashite::Pan.valid?("invalid")     # => false
+```
 
-### Single Action
+#### Parsing
 
+```ruby
+Sashite::Pan.parse(pan_string)
 ```
-<source>,<destination>,<piece>[,<hand_piece>]
+
+Parse a PAN string into an Action object.
+
+**Parameters:**
+- `pan_string` [String] - PAN notation string
+
+**Returns:** [Pan::Action] - Immutable action object
+
+**Raises:** [ArgumentError] - If the PAN string is invalid
+
+**Examples:**
+```ruby
+Sashite::Pan.parse("e2-e4")        # => #<Pan::Action type=:move ...>
+Sashite::Pan.parse("d1+f3")        # => #<Pan::Action type=:capture ...>
+Sashite::Pan.parse("...")          # => #<Pan::Action type=:pass>
 ```
 
-### Multiple Actions
+### Action Class
 
+#### Creation Methods
+
+All creation methods return immutable Action objects.
+
+##### Pass Action
+
+```ruby
+Sashite::Pan::Action.pass
 ```
-<action1>;<action2>[;<action3>...]
+
+Create a pass action (no move, turn ends).
+
+**Returns:** [Action] - Pass action
+
+**Example:**
+```ruby
+action = Sashite::Pan::Action.pass
+action.to_s  # => "..."
 ```
 
-Where:
+##### Movement Actions
 
-- **source**: Origin square label, or `*` for drops from hand
-- **destination**: Target square label
-- **piece**: Piece being moved (PNN format with optional modifiers)
-- **hand_piece**: Optional piece added to mover's hand (captures, promotions)
+```ruby
+Sashite::Pan::Action.move(source, destination, transformation: nil)
+```
 
-## Basic Usage
+Create a move action to an empty square.
 
-### Parsing PAN Strings
+**Parameters:**
+- `source` [String] - Source CELL coordinate
+- `destination` [String] - Destination CELL coordinate
+- `transformation` [String, nil] - Optional EPIN transformation
 
-Convert a PAN string into PMN format (array of action hashes):
+**Returns:** [Action] - Move action
 
+**Examples:**
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.move("e2", "e4")
+# => "e2-e4"
 
-# Simple move
-result = Sashite::Pan.parse("27,18,+P")
-# => [{"src_square"=>"27", "dst_square"=>"18", "piece_name"=>"+P"}]
+Sashite::Pan::Action.move("e7", "e8", transformation: "Q")
+# => "e7-e8=Q"
 
-# Capture with hand piece
-result = Sashite::Pan.parse("36,27,B,P")
-# => [{"src_square"=>"36", "dst_square"=>"27", "piece_name"=>"B", "piece_hand"=>"P"}]
+Sashite::Pan::Action.move("a7", "a8", transformation: "+R")
+# => "a7-a8=+R"
+```
 
-# Drop from hand
-result = Sashite::Pan.parse("*,27,p")
-# => [{"src_square"=>nil, "dst_square"=>"27", "piece_name"=>"p"}]
+---
 
-# Multiple actions (castling)
-result = Sashite::Pan.parse("e1,g1,K;h1,f1,R")
-# => [
-#   {"src_square"=>"e1", "dst_square"=>"g1", "piece_name"=>"K"},
-#   {"src_square"=>"h1", "dst_square"=>"f1", "piece_name"=>"R"}
-# ]
+```ruby
+Sashite::Pan::Action.capture(source, destination, transformation: nil)
 ```
 
-### Safe Parsing
+Create a capture action at destination.
 
-Parse a PAN string without raising exceptions:
+**Parameters:**
+- `source` [String] - Source CELL coordinate
+- `destination` [String] - Destination CELL coordinate (occupied square)
+- `transformation` [String, nil] - Optional EPIN transformation
 
+**Returns:** [Action] - Capture action
+
+**Examples:**
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.capture("d1", "f3")
+# => "d1+f3"
 
-# Valid PAN string
-result = Sashite::Pan.safe_parse("e2,e4,P'")
-# => [{"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"}]
+Sashite::Pan::Action.capture("b7", "a8", transformation: "R")
+# => "b7+a8=R"
+```
 
-# Invalid PAN string
-result = Sashite::Pan.safe_parse("invalid pan string")
-# => nil
+---
+
+```ruby
+Sashite::Pan::Action.special(source, destination, transformation: nil)
 ```
 
-### Creating PAN Strings
+Create a special move action with implicit side effects.
+
+**Parameters:**
+- `source` [String] - Source CELL coordinate
+- `destination` [String] - Destination CELL coordinate
+- `transformation` [String, nil] - Optional EPIN transformation
+
+**Returns:** [Action] - Special action
 
-Convert PMN actions (array of hashes) into a PAN string:
+**Examples:**
+```ruby
+Sashite::Pan::Action.special("e1", "g1")
+# => "e1~g1" (castling)
+
+Sashite::Pan::Action.special("e5", "f6")
+# => "e5~f6" (en passant)
+```
+
+##### Static Capture
 
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.static_capture(square)
+```
 
-# Simple move
-pmn_actions = [{"src_square" => "27", "dst_square" => "18", "piece_name" => "+P"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "27,18,+P"
+Create a static capture action (remove piece without movement).
 
-# Capture with hand piece
-pmn_actions = [{"src_square" => "36", "dst_square" => "27", "piece_name" => "B", "piece_hand" => "P"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "36,27,B,P"
+**Parameters:**
+- `square` [String] - CELL coordinate of piece to capture
+
+**Returns:** [Action] - Static capture action
+
+**Example:**
+```ruby
+Sashite::Pan::Action.static_capture("d4")
+# => "+d4"
+```
 
-# Drop from hand
-pmn_actions = [{"src_square" => nil, "dst_square" => "27", "piece_name" => "p"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "*,27,p"
+##### Drop Actions
 
-# Multiple actions (castling)
-pmn_actions = [
-  {"src_square" => "e1", "dst_square" => "g1", "piece_name" => "K"},
-  {"src_square" => "h1", "dst_square" => "f1", "piece_name" => "R"}
-]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "e1,g1,K;h1,f1,R"
+```ruby
+Sashite::Pan::Action.drop(destination, piece: nil, transformation: nil)
 ```
 
-### Safe Dumping
+Create a drop action to empty square.
+
+**Parameters:**
+- `destination` [String] - Destination CELL coordinate (empty square)
+- `piece` [String, nil] - Optional EPIN piece identifier
+- `transformation` [String, nil] - Optional EPIN transformation
 
-Create PAN strings without raising exceptions:
+**Returns:** [Action] - Drop action
 
+**Examples:**
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.drop("e5", piece: "P")
+# => "P*e5"
 
-# Valid PMN data
-pmn_actions = [{"src_square" => "e2", "dst_square" => "e4", "piece_name" => "P"}]
-result = Sashite::Pan.safe_dump(pmn_actions)
-# => "e2,e4,P"
+Sashite::Pan::Action.drop("d4")
+# => "*d4" (piece type inferred from context)
 
-# Invalid PMN data
-invalid_data = [{"invalid" => "data"}]
-result = Sashite::Pan.safe_dump(invalid_data)
-# => nil
+Sashite::Pan::Action.drop("c3", piece: "S", transformation: "+S")
+# => "S*c3=+S"
 ```
 
-### Validation
+---
+
+```ruby
+Sashite::Pan::Action.drop_capture(destination, piece: nil, transformation: nil)
+```
 
-Check if a string is valid PAN notation:
+Create a drop action with capture.
 
+**Parameters:**
+- `destination` [String] - Destination CELL coordinate (occupied square)
+- `piece` [String, nil] - Optional EPIN piece identifier
+- `transformation` [String, nil] - Optional EPIN transformation
+
+**Returns:** [Action] - Drop capture action
+
+**Example:**
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.drop_capture("b4", piece: "L")
+# => "L.b4"
+```
 
-Sashite::Pan.valid?("27,18,+P")           # => true
-Sashite::Pan.valid?("*,27,p")             # => true
-Sashite::Pan.valid?("e1,g1,K;h1,f1,R")   # => true
+##### Modification Action
 
-Sashite::Pan.valid?("")                   # => false
-Sashite::Pan.valid?("invalid")            # => false
-Sashite::Pan.valid?("27,18")              # => false (missing piece)
+```ruby
+Sashite::Pan::Action.modify(square, piece)
 ```
 
-## Examples
+Create an in-place transformation action.
 
-### Shogi Examples
+**Parameters:**
+- `square` [String] - CELL coordinate
+- `piece` [String] - EPIN piece identifier (final state)
 
+**Returns:** [Action] - Modification action
+
+**Examples:**
 ```ruby
-require "sashite-pan"
+Sashite::Pan::Action.modify("e4", "+P")
+# => "e4=+P"
+
+Sashite::Pan::Action.modify("c3", "k'")
+# => "c3=k'"
+```
 
-# Pawn promotion
-Sashite::Pan.parse("27,18,+P")
-# => [{"src_square"=>"27", "dst_square"=>"18", "piece_name"=>"+P"}]
+#### Instance Methods
 
-# Bishop captures promoted pawn
-Sashite::Pan.parse("36,27,B,P")
-# => [{"src_square"=>"36", "dst_square"=>"27", "piece_name"=>"B", "piece_hand"=>"P"}]
+##### Attribute Access
 
-# Drop pawn from hand
-Sashite::Pan.parse("*,27,p")
-# => [{"src_square"=>nil, "dst_square"=>"27", "piece_name"=>"p"}]
+```ruby
+action.type
 ```
 
-### Chess Examples
+Get the action type.
+
+**Returns:** [Symbol] - One of: `:pass`, `:move`, `:capture`, `:special`, `:static_capture`, `:drop`, `:drop_capture`, `:modify`
+
+---
 
 ```ruby
-require "sashite-pan"
+action.source
+```
 
-# Kingside castling
-Sashite::Pan.parse("e1,g1,K;h1,f1,R")
-# => [
-#   {"src_square"=>"e1", "dst_square"=>"g1", "piece_name"=>"K"},
-#   {"src_square"=>"h1", "dst_square"=>"f1", "piece_name"=>"R"}
-# ]
+Get the source coordinate (for movement actions).
 
-# Pawn with state modifier (can be captured en passant)
-Sashite::Pan.parse("e2,e4,P'")
-# => [{"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"}]
+**Returns:** [String, nil] - CELL coordinate or nil
 
-# En passant capture (multi-step)
-Sashite::Pan.parse("d4,e3,p;e3,e4,p")
-# => [
-#   {"src_square"=>"d4", "dst_square"=>"e3", "piece_name"=>"p"},
-#   {"src_square"=>"e3", "dst_square"=>"e4", "piece_name"=>"p"}
-# ]
+---
+
+```ruby
+action.destination
 ```
 
-## Integration with PMN
+Get the destination coordinate.
 
-PAN is designed to work seamlessly with PMN (Portable Move Notation). You can easily convert between the two formats:
+**Returns:** [String, nil] - CELL coordinate or nil
+
+---
+
+```ruby
+action.piece
+```
+
+Get the piece identifier (for drop/modify actions).
+
+**Returns:** [String, nil] - EPIN identifier or nil
+
+---
+
+```ruby
+action.transformation
+```
+
+Get the transformation piece (for actions with `=<piece>`).
+
+**Returns:** [String, nil] - EPIN identifier or nil
+
+---
 
 ```ruby
-require "sashite-pan"
-require "portable_move_notation"
+action.to_s
+```
 
-# Start with a PAN string
-pan_string = "e2,e4,P';d7,d5,p"
+Convert action to PAN string representation.
 
-# Convert to PMN format
-pmn_actions = Sashite::Pan.parse(pan_string)
-# => [
-#   {"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"},
-#   {"src_square"=>"d7", "dst_square"=>"d5", "piece_name"=>"p"}
-# ]
+**Returns:** [String] - PAN notation
+
+**Examples:**
+```ruby
+Sashite::Pan::Action.move("e2", "e4").to_s
+# => "e2-e4"
+
+Sashite::Pan::Action.drop("e5", piece: "P").to_s
+# => "P*e5"
+```
 
-# Use with PMN library
-move = PortableMoveNotation::Move.new(*pmn_actions.map { |action|
-  PortableMoveNotation::Action.new(**action.transform_keys(&:to_sym))
-})
+##### Type Queries
 
-# Convert back to PAN
-new_pan_string = Sashite::Pan.dump(pmn_actions)
-# => "e2,e4,P';d7,d5,p"
+```ruby
+action.pass?
+action.move?
+action.capture?
+action.special?
+action.static_capture?
+action.drop?
+action.drop_capture?
+action.modify?
+action.movement?        # true for move, capture, or special
+action.drop_action?     # true for drop or drop_capture
 ```
 
-## Use Cases
+Check action type.
+
+**Returns:** [Boolean]
 
-PAN is optimal for:
+**Examples:**
+```ruby
+action = Sashite::Pan.parse("e2-e4")
+action.move?       # => true
+action.movement?   # => true
+action.pass?       # => false
 
-- **Move logging and game records**: Compact storage of game moves
-- **Network transmission**: Efficient move data transmission
-- **Command-line interfaces**: Human-readable move input/output
-- **Quick manual entry**: Easy to type and edit move sequences
-- **Storage optimization**: Space-efficient alternative to JSON
+pass = Sashite::Pan::Action.pass
+pass.pass?         # => true
+
+drop = Sashite::Pan.parse("P*e5")
+drop.drop?         # => true
+drop.drop_action?  # => true
+```
+
+##### Comparison
+
+```ruby
+action == other
+```
 
-PMN is optimal for:
+Check equality between actions.
 
-- **Programmatic analysis**: Complex move processing and validation
-- **JSON-based systems**: Direct integration with JSON APIs
-- **Structured data processing**: Schema validation and type checking
+**Parameters:**
+- `other` [Action] - Action to compare with
 
-## Properties of PAN
+**Returns:** [Boolean] - true if actions are identical
 
-- **Rule-agnostic**: PAN does not encode legality, validity, or game-specific conditions
-- **Space-efficient**: Significantly more compact than equivalent JSON representation
-- **Human-readable**: Easy to read, write, and understand
-- **Lossless conversion**: Perfect bidirectional conversion with PMN format
+**Example:**
+```ruby
+action1 = Sashite::Pan.parse("e2-e4")
+action2 = Sashite::Pan::Action.move("e2", "e4")
+action1 == action2  # => true
+```
 
-## Error Handling
+## Advanced Usage
 
-The library provides detailed error messages for invalid input:
+### Parsing Game Sequences
 
 ```ruby
-require "sashite-pan"
+# Parse a sequence of moves
+moves = %w[e2-e4 e7-e5 g1-f3 b8-c6]
+actions = moves.map { |move| Sashite::Pan.parse(move) }
+
+# Analyze action types
+actions.count(&:move?)     # => 4
+actions.all?(&:movement?)  # => true
+
+# Extract coordinates
+sources = actions.map(&:source)
+destinations = actions.map(&:destination)
+```
 
-begin
-  Sashite::Pan.parse("invalid,pan")  # Missing piece component
-rescue Sashite::Pan::Parser::Error => e
-  puts e.message  # => "Action must have at least 3 components (source, destination, piece)"
+### Action Type Detection
+
+```ruby
+def describe_action(pan_string)
+  action = Sashite::Pan.parse(pan_string)
+
+  case action.type
+  when :pass
+    "Player passes"
+  when :move
+    "Move from #{action.source} to #{action.destination}"
+  when :capture
+    "Capture at #{action.destination}"
+  when :special
+    "Special move: #{action.source} to #{action.destination}"
+  when :drop
+    piece_str = action.piece ? "#{action.piece} " : ""
+    "Drop #{piece_str}at #{action.destination}"
+  when :modify
+    "Transform piece at #{action.square} to #{action.piece}"
+  end
 end
 
-begin
-  Sashite::Pan.dump([{"invalid" => "data"}])  # Missing required fields
-rescue Sashite::Pan::Dumper::Error => e
-  puts e.message  # => "Action must have dst_square"
+describe_action("e2-e4")   # => "Move from e2 to e4"
+describe_action("d1+f3")   # => "Capture at f3"
+describe_action("P*e5")    # => "Drop P at e5"
+describe_action("...")     # => "Player passes"
+```
+
+### Transformation Detection
+
+```ruby
+def has_promotion?(pan_string)
+  action = Sashite::Pan.parse(pan_string)
+  !action.transformation.nil?
+end
+
+has_promotion?("e2-e4")      # => false
+has_promotion?("e7-e8=Q")    # => true
+has_promotion?("P*e5")       # => false
+has_promotion?("S*c3=+S")    # => true
+```
+
+### Building Move Generators
+
+```ruby
+class MoveBuilder
+  def initialize(source)
+    @source = source
+  end
+
+  def to(destination)
+    Sashite::Pan::Action.move(@source, destination)
+  end
+
+  def captures(destination)
+    Sashite::Pan::Action.capture(@source, destination)
+  end
+
+  def to_promoting(destination, piece)
+    Sashite::Pan::Action.move(@source, destination, transformation: piece)
+  end
+end
+
+# Usage
+builder = MoveBuilder.new("e7")
+builder.to("e8").to_s                    # => "e7-e8"
+builder.to_promoting("e8", "Q").to_s     # => "e7-e8=Q"
+builder.captures("d8").to_s              # => "e7+d8"
+```
+
+### Validation Before Parsing
+
+```ruby
+def safe_parse(pan_string)
+  return nil unless Sashite::Pan.valid?(pan_string)
+
+  Sashite::Pan.parse(pan_string)
+rescue ArgumentError
+  nil
 end
+
+safe_parse("e2-e4")      # => #<Pan::Action ...>
+safe_parse("invalid")    # => nil
 ```
 
+### Pattern Matching (Ruby 3.0+)
+
+```ruby
+def analyze(action)
+  case action
+  in { type: :move, source:, destination:, transformation: nil }
+    "Simple move: #{source} → #{destination}"
+  in { type: :move, transformation: piece }
+    "Promotion to #{piece}"
+  in { type: :capture, source:, destination: }
+    "Capture: #{source} takes #{destination}"
+  in { type: :drop, piece:, destination: }
+    "Drop #{piece} at #{destination}"
+  in { type: :pass }
+    "Pass"
+  else
+    "Other action"
+  end
+end
+
+action = Sashite::Pan.parse("e7-e8=Q")
+analyze(action)  # => "Promotion to Q"
+```
+
+## Properties
+
+* **Operator-based**: Intuitive symbols for different action types
+* **Compact notation**: Minimal character usage while maintaining readability
+* **Game-agnostic**: Works across chess, shōgi, xiangqi, and other abstract strategy games
+* **CELL integration**: Uses CELL coordinates for board positions
+* **EPIN integration**: Uses EPIN identifiers for piece representation
+* **Immutable**: All action objects are frozen
+* **Functional**: Pure functions with no side effects
+* **Type-safe**: Strong validation and error handling
+
+## Related Specifications
+
+- [PAN Specification v1.0.0](https://sashite.dev/specs/pan/1.0.0/) - Complete format specification
+- [PAN Examples](https://sashite.dev/specs/pan/1.0.0/examples/) - Usage examples across different games
+- [CELL](https://sashite.dev/specs/cell/) - Coordinate encoding for board positions
+- [EPIN](https://sashite.dev/specs/epin/) - Extended piece identifiers
+- [Game Protocol](https://sashite.dev/protocol/) - Conceptual foundation
+
 ## Documentation
 
-- [Official PAN Specification](https://sashite.dev/documents/pan/1.0.0/)
+- [Official PAN Specification v1.0.0](https://sashite.dev/specs/pan/1.0.0/)
 - [API Documentation](https://rubydoc.info/github/sashite/pan.rb/main)
-- [PMN Specification](https://sashite.dev/documents/pmn/1.0.0/)
+- [PAN Examples](https://sashite.dev/specs/pan/1.0.0/examples/)
+
+## Development
+
+```sh
+# Clone the repository
+git clone https://github.com/sashite/pan.rb.git
+cd pan.rb
+
+# Install dependencies
+bundle install
+
+# Run tests
+ruby test.rb
+
+# Generate documentation
+yard doc
+```
+
+## Contributing
+
+1. Fork the repository
+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
 
-The [gem](https://rubygems.org/gems/sashite-pan) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
-## About Sashité
+## About
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+Maintained by [Sashité](https://sashite.com/) – promoting chess variants and sharing the beauty of board game cultures.