From d4c9a0e2367d254b2fbdf1171fe671752c34bae4 Mon Sep 17 00:00:00 2001
From: benmandrew <benmandrew@gmail.com>
Date: Sat, 13 Jun 2026 20:14:53 +0100
Subject: [PATCH] docs: document ALGORITHM option and wire it into Docker

The --algorithm bfs|bestfirst|astar flag was only reachable via the CLI;
the Docker entrypoint (the documented interface) had no way to select it.
Add an ALGORITHM env var mapped to --algorithm in docker-compose.yml and
the graph entrypoint, and document the three search strategies in the
README. WITH_DFS=true continues to take precedence.
---
 README.md               | 16 +++++++++++++++-
 docker-compose.yml      |  1 +
 docker/Dockerfile.graph |  2 +-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a0499c4..12b8f07 100644
--- a/README.md
+++ b/README.md
@@ -14,12 +14,26 @@ BFS_TIMEOUT_S=0.1 docker compose up
 
 Access the web app on [http://localhost:8080](http://localhost:8080).
 
-By default, the graph will be explored by a breadth-first search (BFS) until the timout. Alternatively, by setting `WITH_DFS=true` as below, it will first explore down a single path, depth-first, using a simple heuristic for the best move in each state. Once no more moves can be made, the BFS is done from every node in the path. Using this heuristic makes it possible to find the winning state, which will be labelled if found.
+By default, the graph will be explored by a breadth-first search (BFS) until the timeout. Alternatively, by setting `WITH_DFS=true` as below, it will first explore down a single path, depth-first, using a simple heuristic for the best move in each state. Once no more moves can be made, the BFS is done from every node in the path. Using this heuristic makes it possible to find the winning state, which will be labelled if found.
 
 ```bash
 WITH_DFS=true BFS_TIMEOUT_S=0.1 docker compose up
 ```
 
+### Search algorithm
+
+Set `ALGORITHM` to choose how the graph is explored (within the same depth/timeout budget):
+
+- `bfs` (default) — breadth-first search; explores every state level by level.
+- `bestfirst` — greedy best-first search ordered by a state heuristic (foundation progress, face-down cards, blocked cards, and free columns), biasing exploration toward promising states.
+- `astar` — A\* search ordered by depth plus an admissible foundation-distance heuristic, reaching winning states along shorter paths first.
+
+```bash
+ALGORITHM=astar BFS_TIMEOUT_S=0.1 docker compose up
+```
+
+`WITH_DFS=true` takes precedence over `ALGORITHM`. All three algorithms build the complete state graph for visualisation; they differ only in which states they expand first when the budget is limited.
+
 ## Build locally
 
 Depends on:
diff --git a/docker-compose.yml b/docker-compose.yml
index 39fc256..51418aa 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,6 +10,7 @@ services:
       BFS_MAX_DEPTH: "${BFS_MAX_DEPTH:-100}"
       BFS_TIMEOUT_S: "${BFS_TIMEOUT_S:-0.05}"
       WITH_DFS: "${WITH_DFS:-false}"
+      ALGORITHM: "${ALGORITHM:-bfs}"
     restart: "no"
     init: true
     healthcheck:
diff --git a/docker/Dockerfile.graph b/docker/Dockerfile.graph
index 4190770..2b3d954 100644
--- a/docker/Dockerfile.graph
+++ b/docker/Dockerfile.graph
@@ -20,4 +20,4 @@ WORKDIR /app
 COPY --from=builder /build/rose ./rose
 RUN mkdir -p /app/shared && chmod 755 /app
 VOLUME ["/app/shared"]
-ENTRYPOINT ["sh", "-c", "if [ \"${WITH_DFS:-false}\" = \"true\" ]; then DFS_FLAG=--with-dfs; else DFS_FLAG=; fi; /app/rose ${DFS_FLAG} --max-depth ${BFS_MAX_DEPTH:-5} --timeout ${BFS_TIMEOUT_S:-0.1} /app/shared && tail -F /dev/null"]
+ENTRYPOINT ["sh", "-c", "if [ \"${WITH_DFS:-false}\" = \"true\" ]; then DFS_FLAG=--with-dfs; else DFS_FLAG=; fi; /app/rose ${DFS_FLAG} --algorithm ${ALGORITHM:-bfs} --max-depth ${BFS_MAX_DEPTH:-5} --timeout ${BFS_TIMEOUT_S:-0.1} /app/shared && tail -F /dev/null"]