chore: address comments

Author: zepfred

core/src/main/java/ai/timefold/solver/core/api/solver/SolverJobBuilder.java

@@ -60,9 +60,9 @@ public interface SolverJobBuilder<Solution_, ProblemId_> {
     /**
      * Sets the best solution consumer, which may be called multiple times during the solving process.
      * <p>
-     * We strongly recommend not applying any changes to the solution instance while the solver runs.
-     * It is essential to understand that the solution instance is not cloned when the event is triggered,
-     * and any modifications may lead to inconsistencies due to its internal reuse.
+     * Don't apply any changes to the solution instance while the solver runs.
+     * The solver's best solution instance is the same as the one in the event,
+     * and any modifications may lead to solver corruption due to its internal reuse.
      *
      * @param bestSolutionConsumer called multiple times for each new best solution on a consumer thread
      * @return this

docs/src/modules/ROOT/pages/using-timefold-solver/running-the-solver.adoc

@@ -764,6 +764,93 @@ The current `SolverManager` implementation runs on a single computer node,
 but future work aims to distribute solver loads across a cloud.
 
 
+[#solverManagerBuilder]
+== The `SolverManager` Builder
+
+The `SolverManager` also enables the creation of a builder to customize and submit a planning problem for solving.
+
+[tabs]
+====
+Java::
++
+[source,java,options="nowrap"]
+----
+public interface SolverManager<Solution_> {
+
+    SolverJobBuilder<Solution_, ProblemId_> solveBuilder();
+
+    ...
+}
+----
+
+Python::
++
+[source,python,options="nowrap"]
+----
+class SolverManager(Generic[Solution_, ProblemId_]):
+    ...
+    def solve_builder(self) -> SolverJobBuilder[Solution_, ProblemId_]:
+        ...
+----
+====
+
+
+A `SolverJobBuilder` includes various settings, as shown in the following code snippet:
+
+[tabs]
+====
+Java::
++
+[source,java,options="nowrap"]
+----
+solverManager.solveBuilder()
+        .withProblemId(problemId)
+        .withProblem(problem)
+        .withFirstInitializedSolutionConsumer(firstInitializedSolutionConsumer)
+        .withBestSolutionConsumer(bestSolutionConsumer)
+        .withFinalBestSolutionConsumer(finalBestSolutionConsumer)
+        .withExceptionHandler(exceptionHandler)
+        .withConfigOverride(configOverride)
+...
+----
+
+Python::
++
+[source,python,options="nowrap"]
+----
+solver_manager.solve_builder()
+        .with_problem_id(problemId)
+        .with_problem(problem)
+        .with_first_initialized_solution_consumer(on_firs_solution_changed)
+        .with_best_solution_consumer(on_best_solution_changed)
+        .with_final_best_solution_consumer(on_final_solution_changed)
+        .with_exception_handler(on_exception_handler)
+        .with_config_override(config_override)
+...
+----
+====
+
+The job's unique ID is specified using `withProblemId(problemId)`,
+while the problem is defined with `withProblem(problem)`.
+A consumer for the first initialized solution can be configured with `withFirstInitializedSolutionConsumer(...)`.
+The solution is returned by the last phase that immediately precedes the first local search phase.
+Whenever a new best solution is generated by the solver,
+it can be consumed by configuring it with `withBestSolutionConsumer(...)`.
+The final best solution consumer,
+which is called at the end of the solving process,
+can be set using `withFinalBestSolutionConsumer(...)`.
+To handle errors that may arise during the solving process,
+set up the  handling logic by defining `withExceptionHandler(...)`.
+Finally, some solver settings, such as the termination configuration, can be overridden using `withConfigOverride(...)`.
+
+[WARNING]
+====
+The solutions returned by the events in `withFirstInitializedSolutionConsumer(...)`
+and `withBestSolutionConsumer(...)` can be reused during the solving process.
+Therefore, do not apply any changes to the solution instance while the solver is running,
+as any modifications may lead to solver corruption.
+====
+
 [#solverManagerSolveBatch]
 === Solve batch problems