From 698ffacd11ff4e00a03c6baa133f203b613a566f Mon Sep 17 00:00:00 2001
From: msjid <majidgeravand@gfuse.it>
Date: Fri, 28 Aug 2026 19:18:32 +0200
Subject: [PATCH] Rewrite README with proper structure and documentation

- Add clear project description and features
- Improve installation and usage instructions
- Add output format documentation
- Include project structure
- Add algorithm details section
- Fix grammar and formatting
- Add GraphViz visualization instructions

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PgzMA4na39RHxCyPHGSPKs
---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 71 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 9edc7c1..723f6ac 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,81 @@
-# kiwifarm
+# Knight's Shortest Path Solver
 
-The algorithm has been developed to address the following problem:
+A Python-based algorithm that finds all shortest paths for a knight on an empty chessboard.
 
-```
-A knight is in a known cell on an empty chessboard and needs to reach another known cell.
+## Problem Description
 
-Write a Python program that can take as input the two positions on the chessboard and returns as output:
+Given two positions on a standard 8x8 chessboard, this program computes:
 
-* the set of all minimum-length sequences to move the piece from the initial cell to the final cell;
-* a graphviz/dot file of the previous "all shortest path" graph.
+- **All minimum-length move sequences** to get a knight from the starting position to the destination
+- **A graph visualization** (in GraphViz/DOT format) showing all shortest paths
+
+## Features
+
+- Finds all optimal solutions (not just one)
+- Generates GraphViz DOT files for visualization
+- Containerized execution for consistency
+- Configurable output naming
+
+## Prerequisites
+
+- Docker (for containerized execution)
+- Python 3.7+ (for running directly)
+- GraphViz (optional, for rendering DOT files)
+
+## Installation & Usage
+
+### Using Docker (Recommended)
+
+Build and run the algorithm:
+
+```bash
+./run.sh build <dest_x> <dest_y> <output_name>
 ```
 
-## Getting started
-You can build and run the algorithm using the run.sh file
+Example:
+```bash
+./run.sh build 4 5 knight_paths
+```
 
-### Build
-To build the algorith and then run it use:
-```
-./run.sh build 4 5 test
-```
-The first element is the build or run commend that will build the container or use an already built one. then it is X and Y cordination of the destination and then the name of the output file
+Or use an existing image:
 
-If you do not want to build it you can use:
+```bash
+./run.sh run <dest_x> <dest_y> <output_name>
 ```
-./run.sh run 4 5 test
+
+### Parameters
+
+- `<dest_x>`: X-coordinate of destination (0-7)
+- `<dest_y>`: Y-coordinate of destination (0-7)
+- `<output_name>`: Base name for output files (no extension)
+
+### Output
+
+The program generates:
+- `<output_name>.txt`: All shortest paths in text format
+- `<output_name>.dot`: GraphViz file for visualization
+
+To visualize the graph:
+
+```bash
+dot -Tpng <output_name>.dot -o <output_name>.png
 ```
+
+## Project Structure
+
+```
+├── README.md
+├── run.sh              # Build and execution script
+├── Dockerfile          # Container configuration
+├── src/
+│   └── knight_solver.py  # Main algorithm
+└── requirements.txt    # Python dependencies
+```
+
+## Algorithm Details
+
+The solver uses BFS (Breadth-First Search) to explore all possible knight moves, ensuring all minimum-length paths are found. It then constructs a directed graph of these paths and outputs the results in both human-readable and GraphViz formats.
+
+## License
+
+See LICENSE file for details.