sashite-pcn 0.2.0 → 0.4.0

data/README.md

@@ -5,35 +5,55 @@
 ![Ruby](https://github.com/sashite/pcn.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/pcn.rb?label=License&logo=github)](https://github.com/sashite/pcn.rb/raw/main/LICENSE.md)
 
-> **PCN** (Portable Chess Notation) implementation for the Ruby language.
+> **PCN** (Portable Chess Notation) - Complete Ruby implementation for game record management
 
-## What is PCN?
+## Table of Contents
 
-PCN (Portable Chess Notation) is a comprehensive, JSON-based format for representing complete chess game records across variants. PCN integrates the Sashité ecosystem specifications (PMN, FEEN, and SNN) to create a unified, rule-agnostic game recording system that supports both traditional single-variant games and cross-variant scenarios.
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Documentation](#api-documentation)
+- [Format Specifications](#format-specifications)
+- [Time Control Examples](#time-control-examples)
+- [Error Handling](#error-handling)
+- [Complete Examples](#complete-examples)
+- [JSON Interoperability](#json-interoperability)
 
-This gem implements the [PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/) as a pure functional library with immutable data structures, providing a clean Ruby interface for parsing, validating, and generating PCN game records.
+## Overview
+
+PCN (Portable Chess Notation) is a comprehensive, JSON-based format for representing complete chess game records across variants. This Ruby implementation provides:
+
+- **Complete game records** with positions, moves, time tracking, and metadata
+- **Time control support** for Fischer, Classical, Byōyomi, Canadian, and more
+- **Rule-agnostic design** supporting all abstract strategy board games
+- **Immutable objects** with functional transformations
+- **Full validation** of all data formats
+- **JSON compatibility** for easy serialization and storage
+
+Implements [PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/).
 
 ## Installation
 
 ```ruby
-# In your Gemfile
+# Gemfile
 gem "sashite-pcn"
 ```
 
-Or install manually:
+Or install directly:
 
 ```sh
 gem install sashite-pcn
 ```
 
-## Dependencies
+### Dependencies
 
-PCN builds upon three foundational Sashité specifications:
+PCN integrates these Sashité specifications (installed automatically):
 
 ```ruby
-gem "sashite-pmn"   # Portable Move Notation
-gem "sashite-feen"  # Forsyth-Edwards Enhanced Notation
-gem "sashite-snn"   # Style Name Notation
+gem "sashite-pan"   # Portable Action Notation (moves)
+gem "sashite-feen"  # Forsyth-Edwards Enhanced Notation (positions)
+gem "sashite-snn"   # Style Name Notation (game variants)
+gem "sashite-cgsn"  # Chess Game Status Notation (game states)
 ```
 
 ## Quick Start
@@ -41,470 +61,532 @@ gem "sashite-snn"   # Style Name Notation
 ```ruby
 require "sashite/pcn"
 
-# Parse a PCN hash
+# Parse a complete game
 game = Sashite::Pcn.parse({
   "setup" => "+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",
   "moves" => [
-    ["e2", "e4", "C:P"],
-    ["e7", "e5", "c:p"]
+    ["e2-e4", 2.5],  # Each move: [PAN notation, seconds spent]
+    ["e7-e5", 3.1]
   ],
   "status" => "in_progress"
 })
 
-# Access game components
-game.setup                    # => #<Sashite::Feen::Position ...>
-game.moves                    # => [#<Sashite::Pmn::Move ...>, ...]
-game.status                   # => "in_progress"
-game.valid?                   # => true
+# Access game data
+game.setup          # => FEEN position object
+game.moves          # => [["e2-e4", 2.5], ["e7-e5", 3.1]]
+game.move_count     # => 2
+game.status         # => CGSN status object
 
-# Convert back to hash
-game.to_h                     # => { "setup" => "...", "moves" => [...], ... }
+# Transform immutably
+new_game = game.add_move(["g1-f3", 1.8])
+final_game = new_game.with_status("checkmate")
 ```
 
-## JSON Integration
+## API Documentation
 
-This gem focuses on the core PCN data structures and does not include JSON parsing/dumping. Use your preferred JSON library:
+For complete API documentation, see [API.md](API.md).
 
-```ruby
-require "json"
-require "sashite/pcn"
+The API documentation includes:
+- All classes and methods
+- Type signatures and parameters
+- Return values and exceptions
+- Code examples for every method
+- Common usage patterns
+- Time control formats
+- Error handling
 
-# Load from JSON file
-json_string = File.read("game.json")
-pcn_hash = JSON.parse(json_string)
-game = Sashite::Pcn.parse(pcn_hash)
+## Format Specifications
 
-# Save to JSON file
-File.write("game.json", JSON.pretty_generate(game.to_h))
+### FEEN (Position)
 
-# Or with Oj for better performance
-require "oj"
-game = Sashite::Pcn.parse(Oj.load_file("game.json"))
-Oj.to_file("game.json", game.to_h)
-```
+```ruby
+# Standard chess starting position
+"+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"
+# └─ board ─────────────────────────────────────────────────────┘ └┘ └─┘
+#                                                               turn styles
 
-## PCN Format
+# Empty board
+"8/8/8/8/8/8/8/8 / U/u"
 
-A PCN document is a hash with five fields:
+# With piece attributes (+ for light, - for dark)
+"+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"
+```
+
+### PAN (Moves)
 
 ```ruby
-{
-  "meta" => {                               # Optional metadata
-    "name" => String,
-    "event" => String,
-    "location" => String,
-    "round" => Integer,
-    "started_on" => "YYYY-MM-DD",
-    "finished_at" => "YYYY-MM-DDTHH:MM:SSZ",
-    "href" => String
-  },
-  "sides" => {                              # Optional player information
-    "first" => {
-      "style" => String,                    # SNN format
-      "name" => String,
-      "elo" => Integer
-    },
-    "second" => {
-      "style" => String,
-      "name" => String,
-      "elo" => Integer
-    }
-  },
-  "setup" => String,                        # Required: FEEN position
-  "moves" => Array,                         # Required: PMN arrays
-  "status" => String                        # Optional: game status
-}
-```
+# Basic movement
+"e2-e4"      # Move from e2 to e4
+"g1-f3"      # Knight from g1 to f3
 
-Only `setup` and `moves` are required. See the [PCN Specification](https://sashite.dev/specs/pcn/1.0.0/) for complete format details.
+# Special moves
+"e1~g1"      # Castling (special path ~)
+"e5~f6"      # En passant (special path ~)
 
-## Usage
+# Captures
+"d1+f3"      # Movement with capture
+"+e5"        # Static capture at e5
 
-### Parsing Game Records
+# Promotions
+"e7-e8=Q"    # Pawn promotion to Queen
+"e4=+P"      # In-place transformation
 
-```ruby
-# From hash
-game_hash = {
-  "setup" => "+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",
-  "moves" => [["e2", "e4", "C:P"]],
-  "status" => "in_progress"
-}
-game = Sashite::Pcn.parse(game_hash)
+# Drops (shogi-style)
+"P*e4"       # Drop piece P at e4
 
-# Validation without exception
-Sashite::Pcn.valid?(game_hash)              # => true
-Sashite::Pcn.valid?({ "setup" => "" })      # => false
+# Pass move
+"..."        # Pass (no action)
 ```
 
-### Creating Game Records
+### CGSN (Status)
 
 ```ruby
-# Create a new game from components
-game = Sashite::Pcn.new(
-  setup: 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"),
-  moves: [
-    Sashite::Pmn.parse(["e2", "e4", "C:P"]),
-    Sashite::Pmn.parse(["e7", "e5", "c:p"])
-  ],
-  status: "in_progress",
-  meta: Sashite::Pcn::Meta.new(
-    event: "World Championship",
-    round: 5
-  ),
-  sides: Sashite::Pcn::Sides.new(
-    first: Sashite::Pcn::Player.new(name: "Alice", elo: 2800, style: "CHESS"),
-    second: Sashite::Pcn::Player.new(name: "Bob", elo: 2750, style: "chess")
-  )
-)
+# Inferable (can be derived from position)
+"checkmate"      # King under inescapable attack
+"stalemate"      # No legal moves, not in check
+"insufficient"   # Neither side can force checkmate
+"in_progress"    # Game continues
+
+# Explicit only (must be declared)
+"resignation"    # Player resigned
+"time_limit"     # Time expired
+"agreement"      # Mutual agreement
+"illegal_move"   # Invalid move played
 ```
 
-### Accessing Game Data
+### SNN (Styles)
 
 ```ruby
-game = Sashite::Pcn.parse(pcn_hash)
-
-# Required fields
-game.setup                                   # => Feen::Position
-game.setup.to_s                              # => FEEN string
-game.moves                                   # => Array of Pmn::Move
-game.moves.size                              # => Number of moves
-game.moves.first.to_a                        # => PMN array
-
-# Optional fields (may be nil)
-game.status                                  # => "in_progress" or nil
-game.meta                                    # => Meta object or nil
-game.sides                                   # => Sides object or nil
-
-# Metadata access (when present)
-game.meta&.event                             # => "World Championship"
-game.meta&.round                             # => 5
-game.meta&.started_on                        # => "2025-11-15"
-game.meta&.finished_at                       # => "2025-11-15T18:45:00Z"
-
-# Player information (when present)
-game.sides&.first&.name                      # => "Alice"
-game.sides&.first&.elo                       # => 2800
-game.sides&.first&.style                     # => "CHESS"
-game.sides&.second&.name                     # => "Bob"
+# Common styles
+"CHESS"          # Western Chess
+"shogi"          # Japanese Chess
+"xiangqi"        # Chinese Chess
+"makruk"         # Thai Chess
+
+# Case indicates piece set
+"CHESS"          # Uppercase = Western pieces
+"chess"          # Lowercase = alternative representation
 ```
 
-### Validation
-
-```ruby
-# Structural validation
-game.valid?                                  # => true/false
+## Time Control Examples
 
-# Detailed validation with errors
-begin
-  Sashite::Pcn.parse(invalid_hash)
-rescue Sashite::Pcn::Error => e
-  puts e.message
-  puts e.class  # Specific error type
-end
+### Fischer/Increment
 
-# Validate individual components
-Sashite::Pcn::Meta.valid?(meta_hash)        # => true/false
-Sashite::Pcn::Sides.valid?(sides_hash)      # => true/false
-Sashite::Pcn::Player.valid?(player_hash)    # => true/false
+```ruby
+# Blitz 5+3 (5 minutes + 3 seconds per move)
+periods: [
+  { time: 300, moves: nil, inc: 3 }
+]
+
+# Rapid 15+10
+periods: [
+  { time: 900, moves: nil, inc: 10 }
+]
+
+# No increment
+periods: [
+  { time: 600, moves: nil, inc: 0 }  # 10 minutes, no increment
+]
 ```
 
-### Working with Moves
+### Classical (Multiple Periods)
 
 ```ruby
-# Add moves to a game (returns new game)
-game = Sashite::Pcn.parse(pcn_hash)
-new_move = Sashite::Pmn.parse(["g1", "f3", "C:N"])
-updated_game = game.add_move(new_move)
-
-# Iterate over moves
-game.moves.each_with_index do |move, index|
-  player = index.even? ? "First player" : "Second player"
-  puts "#{player}: #{move.to_a.inspect}"
-end
-
-# Get move count
-game.move_count                              # => 2
-game.empty?                                  # => false
+# Tournament time control
+periods: [
+  { time: 5400, moves: 40, inc: 0 },   # 90 min for first 40 moves
+  { time: 1800, moves: 20, inc: 0 },   # 30 min for next 20 moves
+  { time: 900, moves: nil, inc: 30 }   # 15 min + 30s/move for rest
+]
 ```
 
-### Immutable Transformations
+### Byōyomi (Japanese)
 
 ```ruby
-# All transformations return new instances
-original = Sashite::Pcn.parse(pcn_hash)
-
-# Update status
-finished = original.with_status("checkmate")
-finished.status                              # => "checkmate"
-original.status                              # => "in_progress" (unchanged)
-
-# Update metadata
-with_meta = original.with_meta(
-  Sashite::Pcn::Meta.new(event: "Tournament")
-)
-
-# Chain transformations
-result = original
-  .with_status("checkmate")
-  .add_move(new_move)
-  .with_meta(updated_meta)
+# 1 hour main + 60 seconds per move (5 periods)
+periods: [
+  { time: 3600, moves: nil, inc: 0 },  # Main time
+  { time: 60, moves: 1, inc: 0 },      # Byōyomi period 1
+  { time: 60, moves: 1, inc: 0 },      # Byōyomi period 2
+  { time: 60, moves: 1, inc: 0 },      # Byōyomi period 3
+  { time: 60, moves: 1, inc: 0 },      # Byōyomi period 4
+  { time: 60, moves: 1, inc: 0 }       # Byōyomi period 5
+]
 ```
 
-## Format Specification
-
-### Document Structure
+### Canadian Overtime
 
 ```ruby
-{
-  "meta" => {                               # Optional metadata
-    "name" => String,
-    "event" => String,
-    "location" => String,
-    "round" => Integer,
-    "started_on" => "YYYY-MM-DD",
-    "finished_at" => "YYYY-MM-DDTHH:MM:SSZ",
-    "href" => String
-  },
-  "sides" => {                              # Optional player information
-    "first" => {
-      "style" => String,                    # SNN format
-      "name" => String,
-      "elo" => Integer
-    },
-    "second" => {
-      "style" => String,
-      "name" => String,
-      "elo" => Integer
-    }
-  },
-  "setup" => String,                        # Required: FEEN position
-  "moves" => Array,                         # Required: PMN arrays
-  "status" => String                        # Optional: game status
-}
+# 1 hour + 5 minutes for every 10 moves
+periods: [
+  { time: 3600, moves: nil, inc: 0 },  # Main time: 1 hour
+  { time: 300, moves: 10, inc: 0 }     # Overtime: 5 min/10 moves
+]
 ```
 
-### Valid Status Values
-
-- `"in_progress"` - Game ongoing
-- `"checkmate"` - Terminal piece checkmated
-- `"stalemate"` - No legal moves available
-- `"bare_king"` - Only terminal piece remains
-- `"mare_king"` - Terminal piece captured
-- `"resignation"` - Player resigned
-- `"illegal_move"` - Illegal move performed
-- `"time_limit"` - Time exceeded
-- `"move_limit"` - Move limit reached
-- `"repetition"` - Position repetition
-- `"agreement"` - Players agreed to end
-- `"insufficient"` - Neither player has sufficient material to force a win
-
-## API Reference
-
-### Main Module Methods
+### No Time Control
 
-- `Sashite::Pcn.parse(hash)` - Parse hash into Game object
-- `Sashite::Pcn.valid?(hash)` - Validate without raising exceptions
-- `Sashite::Pcn.new(**attributes)` - Create game from components
+```ruby
+# Casual/correspondence game
+periods: []      # Empty array
+periods: nil     # Or omit entirely
+```
 
-### Game Class
+## Error Handling
 
-#### Creation
-- `Sashite::Pcn::Game.new(setup:, moves:, status: nil, meta: nil, sides: nil)`
+```ruby
+# Setup validation
+begin
+  game = Sashite::Pcn::Game.new(setup: "invalid")
+rescue ArgumentError => e
+  puts e.message  # => "Invalid FEEN format"
+end
 
-#### Attributes (read-only)
-- `#setup` - Feen::Position object (required)
-- `#moves` - Array of Pmn::Move objects (required)
-- `#status` - String or nil (optional)
-- `#meta` - Meta object or nil (optional)
-- `#sides` - Sides object or nil (optional)
+# Move validation
+begin
+  game.add_move(["invalid", -5])
+rescue ArgumentError => e
+  puts e.message  # => "Invalid PAN notation"
+end
 
-#### Queries
-- `#valid?` - Check overall validity
-- `#move_count` / `#size` - Number of moves
-- `#empty?` - No moves played
-- `#has_status?` - Status field present
-- `#has_meta?` - Metadata present
-- `#has_sides?` - Player information present
+# Move format validation
+begin
+  game.add_move("e2-e4")  # Wrong: should be array
+rescue ArgumentError => e
+  puts e.message  # => "Each move must be [PAN string, seconds float] tuple"
+end
 
-#### Transformations (immutable)
-- `#add_move(pmn_move)` - Add move (returns new game)
-- `#with_status(status)` - Update status (returns new game)
-- `#with_meta(meta)` - Update metadata (returns new game)
-- `#with_sides(sides)` - Update player info (returns new game)
+# Metadata validation
+begin
+  Sashite::Pcn::Game.new(
+    setup: "8/8/8/8/8/8/8/8 / U/u",
+    meta: { round: -1 }  # Invalid: must be >= 1
+  )
+rescue ArgumentError => e
+  puts e.message  # => "round must be a positive integer (>= 1)"
+end
 
-#### Conversion
-- `#to_h` - Convert to hash
-- `#to_s` - Alias for pretty-printed hash representation
+# Time control validation
+begin
+  sides = {
+    first: {
+      periods: [
+        { time: -100 }  # Invalid: negative time
+      ]
+    }
+  }
+rescue ArgumentError => e
+  puts e.message  # => "time must be a non-negative integer (>= 0)"
+end
+```
 
-### Meta Class
+## Complete Examples
 
-- `Sashite::Pcn::Meta.new(**attributes)`
-- `#name`, `#event`, `#location`, `#round`
-- `#started_on`, `#finished_at`, `#href`
-- `#to_h` - Convert to hash
-- `Meta.valid?(hash)` - Validate metadata
+### Minimal Valid Game
 
-### Sides Class
+```ruby
+# Absolute minimum (only setup required)
+game = Sashite::Pcn::Game.new(
+  setup: "8/8/8/8/8/8/8/8 / U/u"
+)
+```
 
-- `Sashite::Pcn::Sides.new(first:, second:)`
-- `#first` - First player (Player object or nil)
-- `#second` - Second player (Player object or nil)
-- `#to_h` - Convert to hash
-- `Sides.valid?(hash)` - Validate sides
+### Standard Chess Game
 
-### Player Class
+```ruby
+game = Sashite::Pcn::Game.new(
+  meta: {
+    name: "Italian Game",
+    event: "Online Tournament",
+    round: 3,
+    started_at: "2025-01-27T19:30:00Z"
+  },
+  sides: {
+    first: {
+      name: "Alice",
+      elo: 2100,
+      style: "CHESS",
+      periods: [{ time: 300, moves: nil, inc: 3 }]  # 5+3 blitz
+    },
+    second: {
+      name: "Bob",
+      elo: 2050,
+      style: "chess",
+      periods: [{ time: 300, moves: nil, inc: 3 }]
+    }
+  },
+  setup: "+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",
+  moves: [
+    ["e2-e4", 2.3],
+    ["c7-c5", 3.1],
+    ["g1-f3", 1.8],
+    ["d7-d6", 2.5],
+    ["d2-d4", 4.2],
+    ["c5+d4", 1.0],
+    ["f3+d4", 0.8]
+  ],
+  status: "in_progress"
+)
+```
 
-- `Sashite::Pcn::Player.new(style: nil, name: nil, elo: nil)`
-- `#style` - SNN style name or nil
-- `#name` - Player name or nil
-- `#elo` - Elo rating or nil
-- `#to_h` - Convert to hash
-- `Player.valid?(hash)` - Validate player
+### Building a Game Progressively
 
-### Exceptions
+```ruby
+# Start with minimal game
+game = Sashite::Pcn::Game.new(
+  setup: "+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"
+)
 
-- `Sashite::Pcn::Error` - Base error class
-- `Sashite::Pcn::ParseError` - Structure parsing failed
-- `Sashite::Pcn::ValidationError` - Format validation failed
-- `Sashite::Pcn::SemanticError` - Semantic consistency violation
+# Add metadata
+game = game.with_meta(
+  event: "Friendly Match",
+  started_at: Time.now.utc.iso8601
+)
 
-## Examples
+# Play moves
+game = game.add_move(["e2-e4", 5.2])
+game = game.add_move(["e7-e5", 3.8])
+game = game.add_move(["g1-f3", 2.1])
+
+# Check progress
+puts "Moves played: #{game.move_count}"
+puts "White time: #{game.first_player_time}s"
+puts "Black time: #{game.second_player_time}s"
+
+# Finish game
+if some_condition
+  game = game.with_status("checkmate")
+elsif another_condition
+  game = game.with_status("resignation")
+end
+```
 
-### Traditional Chess Game
+### Complex Tournament Game
 
 ```ruby
-chess_game = Sashite::Pcn.parse({
+require "sashite/pcn"
+require "json"
+
+# Full tournament game with all features
+game_data = {
   "meta" => {
-    "event" => "World Championship",
-    "round" => 5,
-    "started_on" => "2025-11-15"
+    "name" => "Sicilian Defense, Najdorf Variation",
+    "event" => "FIDE World Championship",
+    "location" => "Dubai, UAE",
+    "round" => 11,
+    "started_at" => "2025-11-20T15:00:00+04:00",
+    "href" => "https://worldchess.com/match/2025/round11",
+
+    # Custom metadata
+    "arbiter" => "John Smith",
+    "opening_eco" => "B90",
+    "opening_name" => "Sicilian Najdorf",
+    "board_number" => 1,
+    "section" => "Open",
+    "live_url" => "https://chess24.com/watch/live"
   },
+
   "sides" => {
     "first" => {
       "name" => "Magnus Carlsen",
       "elo" => 2830,
-      "style" => "CHESS"
+      "style" => "CHESS",
+      "title" => "GM",  # Custom field
+      "federation" => "NOR",  # Custom field
+      "periods" => [
+        { "time" => 5400, "moves" => 40, "inc" => 0 },
+        { "time" => 1800, "moves" => 20, "inc" => 0 },
+        { "time" => 900, "moves" => nil, "inc" => 30 }
+      ]
     },
     "second" => {
       "name" => "Fabiano Caruana",
       "elo" => 2820,
-      "style" => "chess"
+      "style" => "chess",
+      "title" => "GM",
+      "federation" => "USA",
+      "periods" => [
+        { "time" => 5400, "moves" => 40, "inc" => 0 },
+        { "time" => 1800, "moves" => 20, "inc" => 0 },
+        { "time" => 900, "moves" => nil, "inc" => 30 }
+      ]
     }
   },
+
   "setup" => "+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",
+
   "moves" => [
-    ["e2", "e4", "C:P"],
-    ["e7", "e5", "c:p"],
-    ["g1", "f3", "C:N"],
-    ["b8", "c6", "c:n"]
+    ["e2-e4", 32.1], ["c7-c5", 28.5],
+    ["g1-f3", 45.2], ["d7-d6", 31.0],
+    ["d2-d4", 38.9], ["c5+d4", 29.8],
+    ["f3+d4", 15.5], ["g8-f6", 35.2],
+    ["b1-c3", 62.3], ["a7-a6", 44.1],
+    # ... many more moves
   ],
-  "status" => "in_progress"
-})
 
-chess_game.move_count                        # => 4
-chess_game.sides.first.name                  # => "Magnus Carlsen"
-```
+  "status" => "resignation"
+}
 
-### Cross-Style Game
+# Parse and use
+game = Sashite::Pcn.parse(game_data)
 
-```ruby
-hybrid_game = Sashite::Pcn.parse({
-  "sides" => {
-    "first" => { "style" => "CHESS" },
-    "second" => { "style" => "makruk" }
-  },
-  "setup" => "rnsmksnr/8/pppppppp/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/m",
-  "moves" => [
-    ["e2", "e4", "C:P"],
-    ["d6", "d5", "m:p"]
-  ],
-  "status" => "in_progress"
-})
+# Analysis
+puts "Game: #{game.meta[:name]}"
+puts "Duration: #{(game.first_player_time + game.second_player_time) / 60} minutes"
+puts "Winner: #{game.status == 'resignation' ? 'First player (White)' : 'Unknown'}"
+puts "Total moves: #{game.move_count}"
+
+# Export to JSON file
+File.write("game.json", JSON.generate(game.to_h))
 ```
 
-### Shōgi Game
+## JSON Interoperability
+
+### Reading PCN Files
 
 ```ruby
-shogi_game = Sashite::Pcn.parse({
-  "setup" => "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / S/s",
-  "moves" => [
-    ["e1", "e2", "S:P"],
-    ["*", "e5", "s:p"]  # Drop from hand
-  ],
-  "status" => "in_progress"
-})
+require "json"
+require "sashite/pcn"
+
+# From file
+json_data = File.read("game.pcn.json")
+hash = JSON.parse(json_data)
+game = Sashite::Pcn.parse(hash)
+
+# From URL
+require "net/http"
+require "uri"
+
+uri = URI("https://api.example.com/game/123")
+response = Net::HTTP.get(uri)
+hash = JSON.parse(response)
+game = Sashite::Pcn.parse(hash)
 ```
 
-### Minimal Valid Game
+### Writing PCN Files
 
 ```ruby
-minimal = Sashite::Pcn.parse({
-  "setup" => "8/8/8/8/8/8/8/8 / C/c",
-  "moves" => []
-})
+# Save to file
+game_hash = game.to_h
+json = JSON.pretty_generate(game_hash)
+File.write("game.pcn.json", json)
 
-minimal.valid?                               # => true
-minimal.empty?                               # => true
-minimal.has_status?                          # => false
+# Send to API
+require "net/http"
+
+uri = URI("https://api.example.com/games")
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
+
+request = Net::HTTP::Post.new(uri)
+request["Content-Type"] = "application/json"
+request.body = JSON.generate(game.to_h)
+
+response = http.request(request)
 ```
 
-## Design Properties
+### Database Storage
+
+```ruby
+# Store in database (e.g., PostgreSQL with JSON column)
+class GameRecord < ActiveRecord::Base
+  # Assumes: t.json :pcn_data
+
+  def game
+    @game ||= Sashite::Pcn.parse(pcn_data)
+  end
+
+  def game=(game_object)
+    self.pcn_data = game_object.to_h
+    @game = game_object
+  end
+end
 
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Comprehensive**: Complete game records with metadata
-- **Immutable**: All objects frozen, transformations return new instances
-- **Functional**: Pure functions without side effects
-- **Composable**: Built on PMN, FEEN, and SNN specifications
-- **Type-safe**: Strong validation at all levels
-- **JSON-compatible**: Native Ruby hash structure ready for JSON serialization
-- **Minimal API**: Small, focused public interface
-- **Library-agnostic**: No JSON parser dependency, use your preferred library
+# Usage
+record = GameRecord.new
+record.game = Sashite::Pcn::Game.new(setup: "...")
+record.save!
+
+# Retrieve
+record = GameRecord.find(id)
+game = record.game
+puts game.move_count
+```
 
-## Related Specifications
+## Properties
 
-- [PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/) - Complete technical specification
-- [PCN Examples](https://sashite.dev/specs/pcn/1.0.0/examples/) - Comprehensive examples
-- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
-- [FEEN](https://sashite.dev/specs/feen/) - Forsyth-Edwards Enhanced Notation
-- [SNN](https://sashite.dev/specs/snn/) - Style Name Notation
+- **Immutable**: All objects are frozen; transformations return new instances
+- **Validated**: All data is validated on creation
+- **Type-safe**: Strong type checking throughout
+- **Rule-agnostic**: Independent of specific game rules
+- **JSON-native**: Direct serialization to/from JSON
+- **Comprehensive**: Complete game information including time tracking
+- **Extensible**: Custom metadata and player fields supported
 
 ## Documentation
 
 - [Official PCN Specification v1.0.0](https://sashite.dev/specs/pcn/1.0.0/)
-- [PCN Examples Documentation](https://sashite.dev/specs/pcn/1.0.0/examples/)
+- [PCN Examples](https://sashite.dev/specs/pcn/1.0.0/examples/)
 - [API Documentation](https://rubydoc.info/github/sashite/pcn.rb/main)
+- [PAN Specification](https://sashite.dev/specs/pan/) (moves)
+- [FEEN Specification](https://sashite.dev/specs/feen/) (positions)
+- [SNN Specification](https://sashite.dev/specs/snn/) (styles)
+- [CGSN Specification](https://sashite.dev/specs/cgsn/) (statuses)
 
 ## Development
 
 ```sh
-# Clone the repository
+# Setup
 git clone https://github.com/sashite/pcn.rb.git
 cd pcn.rb
-
-# Install dependencies
 bundle install
 
 # Run tests
+bundle exec rake test
+# or
 ruby test.rb
 
+# Run linter
+bundle exec rubocop
+
 # Generate documentation
-yard doc
+bundle exec yard doc
+
+# Console for experimentation
+bundle exec irb -r ./lib/sashite/pcn
 ```
 
 ## 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
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for your changes
+4. Implement your feature
+5. Ensure all tests pass (`ruby test.rb`)
+6. Check code style (`rubocop`)
+7. Commit your changes (`git commit -am 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+Released under the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About
 
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Maintained by [Sashité](https://sashite.com/)
+
+> Sashité is a community initiative promoting chess variants and sharing the beauty of traditional board game cultures from around the world.
+
+### Contact
+
+- Website: https://sashite.com
+- GitHub: https://github.com/sashite
+- Email: contact@sashite.com
+
+### Related Projects
+
+- [Pan.rb](https://github.com/sashite/pan.rb) - Portable Action Notation
+- [Feen.rb](https://github.com/sashite/feen.rb) - Forsyth-Edwards Enhanced Notation
+- [Snn.rb](https://github.com/sashite/snn.rb) - Style Name Notation
+- [Cgsn.rb](https://github.com/sashite/cgsn.rb) - Chess Game Status Notation