docs: link getting started structure

docs/src/modules/ROOT/pages/_attributes.adoc

@@ -1,7 +1,8 @@
 // Attributes derived from the maven build, typically versions, are defined in the pom.xml and antora.yml.
 :quickstarts-clone-url: https://github.com/TimefoldAI/timefold-quickstarts
 :quickstarts-archive-url: https://github.com/TimefoldAI/timefold-quickstarts/archive/refs/heads/stable.tar.gz
-:hello-world-java-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/java/hello-world
-:spring-boot-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/java/spring-boot-integration
-:quarkus-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/java/school-timetabling
-:vrp-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/java/vehicle-routing
+:hello-world-java-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/getting-started/hello-world
+:spring-boot-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/getting-started/spring-boot-integration
+:quarkus-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/getting-started/school-timetabling
+:vrp-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/getting-started/vehicle-routing
+:service-quickstart-url: https://github.com/TimefoldAI/timefold-quickstarts/tree/stable/getting-started/service

docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc

@@ -4,6 +4,9 @@
 :sectnums:
 :icons: font
 
+include::../../_attributes.adoc[]
+:framework-quickstart-url: {service-quickstart-url}
+
 This guide walks you through the process of creating an AI Optimization service.
 
 With this approach, you define your planning model: the domain objects, constraints, and planning solution.
@@ -17,11 +20,7 @@ IMPORTANT: This is a preview feature subject to change.
 include::../shared/_whatyoubuild.adoc[]
 
 [sectnums!]
-== Solution source code
-
-In case you get stuck during this Getting Started guide, it might be worth checking the solution project.
-
-This https://github.com/TimefoldAI/timefold-service-getting-started[solution can be found on GitHub].
+include::../shared/_solutionsourcecode.adoc[]
 
 [sectnums!]
 == Prerequisites
@@ -455,6 +454,22 @@ Important elements to observe in the JSON above:
 - The `solverStatus` is `SOLVING_COMPLETED`, indicating the solver has finished optimizing.
 - The `score` is `0hard/0medium/0soft`, signaling that no constraints were broken.
 
+== Generating the initial OpenAPI specification
+
+Before running a full build with `mvn install`, you need to generate the initial OpenAPI specification file.
+The build compares the generated spec against `src/build/openapi.json` to catch accidental API changes,
+so the build will fail if that file does not exist yet.
+
+Run the following command once to create it:
+
+[source,bash,options="nowrap"]
+----
+mvn clean package -Dupdate-api
+----
+
+We recommend committing `src/build/openapi.json` to version control.
+See xref:running-timefold-solver/service/rest-api.adoc#deliberateAPIChanges[Deliberate API changes] for more details on how this mechanism works.
+
 [sectnums!]
 == Next
 

docs/src/modules/ROOT/pages/quickstart/shared/_solutionsourcecode.adoc

@@ -2,16 +2,4 @@
 
 Follow the instructions in the next sections to create the application step by step (recommended).
 
-Alternatively, you can also skip right to the completed example:
-
-. Clone the Git repository:
-+
-[source,shell,subs=attributes+]
-----
-$ git clone {quickstarts-clone-url}
-----
-+
-or download an {quickstarts-archive-url}[archive].
-
-. Find the solution in {framework-quickstart-url}[the `java` directory]
-and run it (see its README file).
+In case you get stuck during this Getting Started guide, it might be worth checking the solution project {framework-quickstart-url}[on GitHub].