docs: new nav structure

[TomCools]

A new nav structure with subheadings has been implemented.
This adjusts the nav.adoc file to make use of that.

[Copilot]

🟡 Changes recommended

The updated nav.adoc contains invalid/incorrect list and link syntax (missing *, incorrect nesting levels, and malformed external link attribute lists) that will likely break or misrender the documentation navigation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the Antora documentation navigation (nav.adoc) to use the new grouped nav structure with subheadings and reorganized sections.

Changes:

• Introduces titled nav groups (for example, “Getting started”, “Domain modeling”) and restructures list nesting.
• Adds new “Upgrading Timefold Solver” entries (including release notes) and an “Additional resources” group.
• Reorders existing sections to fit the new hierarchy.

File summaries

File	Description
docs/src/modules/ROOT/nav.adoc	Reworks the Antora nav structure to use group headings and updated link organization.

Review details

Suppressed comments (5)

docs/src/modules/ROOT/nav.adoc:48

• The '.Deploying to the Timefold Platform' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Deploying to the Timefold Platform
** xref:deploying-to-platform/introduction.adoc[Overview]
** xref:deploying-to-platform/guide.adoc[Guide]
** xref:deploying-to-platform/model-metadata.adoc[leveloffset=+1]
** xref:deploying-to-platform/metrics.adoc[leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:63

• The '.Responding to change' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Responding to change
** xref:responding-to-change/continuous-planning.adoc[leveloffset=+1]
** xref:responding-to-change/real-time-planning.adoc[leveloffset=+1]
** xref:responding-to-change/non-disruptive-replanning.adoc[leveloffset=+1]
** xref:responding-to-change/recommendation-api.adoc[leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:67

• The '.Example use cases' section starts its items at ** level without a parent *, which breaks the nav list structure; change these items to * level.

.Example use cases
** xref:quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc[Vehicle routing (guide)]
** https://github.com/TimefoldAI/timefold-quickstarts[More examples on GitHub^]

docs/src/modules/ROOT/nav.adoc:83

• The '.Commercial editions' section starts its items at ** level without a parent *, which breaks the nav list structure; change these entries to * level.

.Commercial editions
** xref:commercial-editions/commercial-editions.adoc[Overview]
** xref:commercial-editions/installation.adoc[Installation]
** xref:commercial-editions/performance-improvements.adoc[leveloffset=+1]
** xref:constraints-and-score/understanding-the-score.adoc[Score analysis]

docs/src/modules/ROOT/nav.adoc:54

• The '.Optimization algorithms' section uses **/*** nesting without a top-level * parent item, which will mis-nest or invalidate the nav list; shift the first level to * and nest subitems under it.

.Optimization algorithms
** xref:optimization-algorithms/overview.adoc[Overview]
** xref:optimization-algorithms/construction-heuristics.adoc[leveloffset=+1]
** xref:optimization-algorithms/local-search.adoc[leveloffset=+1]
** xref:optimization-algorithms/exhaustive-search.adoc[leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The updated nav file includes syntax that likely prevents the Introduction item from showing and may render stray [leveloffset=+1] text for external links.

Review details

Suppressed comments (2)

docs/src/modules/ROOT/nav.adoc:73

• The external links use a double-bracket syntax (...[Text][leveloffset=+1]) that AsciiDoc will treat as stray text and can break or pollute the rendered nav.

* https://github.com/TimefoldAI/timefold-solver/releases[New and noteworthy][leveloffset=+1]
* xref:upgrading-timefold-solver/overview.adoc[leveloffset=+1]
* xref:upgrading-timefold-solver/upgrade-from-v1.adoc[leveloffset=+1]
* https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-from-optaplanner[Upgrading from OptaPlanner][leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:1

• The introduction entry is no longer a list item, which likely prevents it from appearing in the Antora navigation.

xref:introduction.adoc[leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The nav includes external links with two bracketed attribute lists (e.g. ...[Label][leveloffset=+1]), which is invalid AsciiDoc macro syntax and may render incorrectly in the sidebar.

Review details

Suppressed comments (2)

docs/src/modules/ROOT/nav.adoc:70

• These external-link nav entries use two bracketed attribute lists, but AsciiDoc link macros accept only a single attribute list so the trailing "[leveloffset=+1]" will likely render as literal text or be ignored.

* https://github.com/TimefoldAI/timefold-solver/releases[New and noteworthy][leveloffset=+1]

docs/src/modules/ROOT/nav.adoc:73

• This external-link nav entry uses two bracketed attribute lists, but AsciiDoc link macros accept only a single attribute list so the trailing "[leveloffset=+1]" will likely render as literal text or be ignored.

* https://docs.timefold.ai/timefold-solver/1.x/upgrading-timefold-solver/upgrade-from-optaplanner[Upgrading from OptaPlanner][leveloffset=+1]

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved moderate findings affect URL preservation and the correctness and consistency of the migration guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (6)

Previously missed (1) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Deleting the old backwards-compatibility.adoc page removes its public URL, so existing bookmarks and external links now return 404; preserve it by adding :page-aliases: upgrading-timefold-solver/backwards-compatibility.adoc to this document's header.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:69

• “Unsecure” is not the established adjective for this security warning and reads incorrectly; use “insecure”.

* The unsecure module `persistence-xstream` is removed, because of old, unresolved CVEs in XStream.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:14

• Java is incorrectly lowercased in this user-facing instruction, and the list is missing a serial comma; capitalize it and make the sentence grammatically clear.

Run the command below to upgrade your java, build and other code automatically.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:17

• This page is now exposed in the current 2.x navigation and its command resolves {timefold-solver-version}, but the manual section still describes a Timefold Solver 1.x migration and then points users to the 2.x recipe, leaving the documented upgrade path internally contradictory; either keep this page under the 1.x documentation or rewrite it for the OptaPlanner-to-2.x migration.

NOTE: The script below upgrades your OptaPlanner project to the latest Timefold Solver version, which is {timefold-solver-version}.
This is a significant jump and might require additional migrations. Do check out our other guide for more details on how to the xref:upgrading-timefold-solver/upgrade-from-v1.adoc[upgrade to 2.x range.]

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:26

• The ToLatest recipe shown here does not migrate OptaPlanner coordinates or imports: the repository implementation has no org.optaplanner/optaplanner transformations, so running this command on an OptaPlanner project leaves the advertised upgrade incomplete; add a dedicated OptaPlanner recipe or remove this automatic path.

mvn org.openrewrite.maven:rewrite-maven-plugin:{rewrite-maven-plugin-version}:run -Drewrite.recipeArtifactCoordinates=ai.timefold.solver:timefold-solver-migration:{timefold-solver-version} -Drewrite.activeRecipes=ai.timefold.solver.migration.ToLatest

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:71

• Backticks make ScoreConverter look like a concrete replacement type, but this repository exposes score-specific classes such as HardSoftScoreConverter and no generic ScoreConverter, so the migration instruction is not actionable.

Use JPA's `ScoreConverter` instead.

• Files reviewed: 7/7 changed files
• Comments generated: 5
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Correct the Antora section syntax and preserve the legacy page URL and fragment before approval.

Review details

Suppressed comments (10)

Previously missed (1) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Moving the content out of backwards-compatibility.adoc without an alias removes that established page URL and its #backwardsCompatibility fragment, so existing bookmarks and links break; preserve the old path with :page-aliases: and retain the explicit anchor.

docs/src/modules/ROOT/nav.adoc:3

• Antora section titles require a period followed by a space, so .Getting started is not parsed as a section heading and the new navigation grouping is lost; write . Getting started instead.

.Getting started

docs/src/modules/ROOT/nav.adoc:11

• Antora section titles require a period followed by a space, so .Build with Timefold is not parsed as a section heading and the new navigation grouping is lost; write . Build with Timefold instead.

.Build with Timefold

docs/src/modules/ROOT/nav.adoc:55

• Antora section titles require a period followed by a space, so .Deploying to the Timefold Platform is not parsed as a section heading and the new navigation grouping is lost; write . Deploying to the Timefold Platform instead.

.Deploying to the Timefold Platform

docs/src/modules/ROOT/nav.adoc:61

• Antora section titles require a period followed by a space, so .Optimization algorithms is not parsed as a section heading and the new navigation grouping is lost; write . Optimization algorithms instead.

.Optimization algorithms

docs/src/modules/ROOT/nav.adoc:70

• Antora section titles require a period followed by a space, so .Upgrading Timefold Solver is not parsed as a section heading and the new navigation grouping is lost; write . Upgrading Timefold Solver instead.

.Upgrading Timefold Solver

docs/src/modules/ROOT/nav.adoc:80

• Antora section titles require a period followed by a space, so .Commercial editions is not parsed as a section heading and the new navigation grouping is lost; write . Commercial editions instead.

.Commercial editions

docs/src/modules/ROOT/nav.adoc:94

• Antora section titles require a period followed by a space, so .Additional resources is not parsed as a section heading and the new navigation grouping is lost; write . Additional resources instead.

.Additional resources

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:14

• Capitalize the programming language name as Java here, matching the proper-noun usage in the manual upgrade list below.

Run the command below to upgrade your java, build and other code automatically.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:69

• Use insecure rather than unsecure here; the module is unsafe because of unresolved CVEs.

* The unsecure module `persistence-xstream` is removed, because of old, unresolved CVEs in XStream.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved aggregate-document inclusion and backward-compatibility issues must be addressed.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (8)

Previously missed (1) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Deleting backwards-compatibility.adoc and moving its content here removes both the old upgrading-timefold-solver/backwards-compatibility URL and its explicit #backwardsCompatibility fragment, so add a :page-aliases: entry for the old page and retain that anchor on this section.

docs/src/modules/ROOT/nav.adoc:70

• The new page is not included by .optimization-algorithms.adoc, which is what the root guide includes, so removing this section from move-selector-reference causes Custom moves to disappear from the aggregate user guide and PDF; add an include::custom-moves.adoc[leveloffset=+1] there.

* xref:deploying-to-platform/guide.adoc[Guide]

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:87

• The snippet declares MoveIteratorFactory with one type parameter and raw Move iterators, but the implementation below uses the two-parameter API, so the shown interface and example cannot compile together; mirror the actual MoveIteratorFactory<Solution_, Move_ extends Move<Solution_>> signatures.

public interface MoveIteratorFactory<Solution_> {

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:180

• The example uses Random as the overridden parameter, while the current API requires RandomGenerator, so the @Override at line 178 will fail; use RandomGenerator here.

    public Iterator<MyChangeMove> createRandomMoveIterator(ScoreDirector<MyPlanningSolution> scoreDirector,
            Random workingRandom) {

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:118

• The comment is missing is in if it too expensive; change it to if it is too expensive.

        // if it too expensive to calculate or unknown

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:197

• The comment is missing is in there at least one value; change it to there is at least one value.

                    // This assumes there at least one value that can be assigned to the selected entity

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:2

• This new page is not included by optimization-algorithms/.optimization-algorithms.adoc, so the single-page user guide built from .index.adoc omits the custom-move content even though the nav exposes it; add this page to the optimization aggregate.

== Custom moves

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:69

• The adjective unsecure is incorrect here; use insecure.

* The unsecure module `persistence-xstream` is removed, because of old, unresolved CVEs in XStream.

• Files reviewed: 9/9 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Final review comments identify documentation accuracy, compatibility, aggregation, and navigation issues that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (7)

Previously missed (2) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:95

• This example shows the obsolete one-parameter/raw MoveIteratorFactory signature instead of the current MoveIteratorFactory<Solution_, Move_ extends Move<Solution_>> and Iterator<Move_> contract, so the sample is not an accurate implementation template.

This issue also appears on line 179 of the same file.
docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Deleting upgrading-timefold-solver/backwards-compatibility.adoc without aliasing it from this replacement page breaks existing links to the published page; add the deleted path to :page-aliases:.

docs/src/modules/ROOT/nav.adoc:64

• Adding this page only to nav.adoc leaves it out of the pages/.index.adoc → optimization-algorithms/.optimization-algorithms.adoc single-page aggregation, so the root user guide will omit the entire Custom moves section; add an include for custom-moves.adoc to that hidden aggregator as well.

*** xref:optimization-algorithms/custom-moves.adoc[Move definition]

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:38

• This snippet no longer matches MoveListFactory.createMoveList, whose current return type is List<? extends Move<Solution_>>; as written it teaches a raw and inaccurate declaration.

public interface MoveListFactory<Solution_> {

    List<Move> createMoveList(Solution_ solution);

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:180

• The sample implementation still accepts Random, but the current MoveIteratorFactory contract requires RandomGenerator, so this @Override cannot compile; change the parameter type.

    public Iterator<MyChangeMove> createRandomMoveIterator(ScoreDirector<MyPlanningSolution> scoreDirector,
            Random workingRandom) {

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:1

• Moving this section out of move-selector-reference.adoc removes the previously published #customMovesIntroduction, #generatingCustomMoves, #moveListFactory, and #moveIteratorFactory targets, so existing deep links will 404; retain compatibility anchors or redirects in the old page.

[#customMovesIntroduction]

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:24

• Because this file is now a standalone page with a level-one document title, === Generating custom moves skips the required level-two section and leaves its ==== children at the wrong depth, so change this section to == and the two factory headings to ===.

=== Generating custom moves

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Unresolved navigation, compatibility-link, aggregator, and API-example issues remain.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (10)

Previously missed (2) — in code that hasn't changed since the last review.

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:93

• These iterator signatures use raw Iterator<Move> and Random, but the current interface has a Move_ extends Move<Solution_> type parameter and requires Iterator<Move_> plus RandomGenerator, so this interface example is no longer accurate.

This issue also appears on line 179 of the same file.
docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Moving the contents out of backwards-compatibility.adoc removes its public URL and the #backwardsCompatibility anchor, so existing links will no longer resolve; add a page alias in this document's header and preserve the old anchor.

docs/src/modules/ROOT/nav.adoc:1

• The old navigation entry for introduction.adoc is removed without a replacement, so the introductory page is no longer discoverable from the sidebar; retain it under the new Getting started section.

.Getting started

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:1

• This new page is not included by the optimization-algorithms/.optimization-algorithms.adoc single-page aggregator, so it will appear in the navigation but be missing from single-page builds; add it to that aggregator.

[#customMovesIntroduction]

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:38

• This example uses the obsolete raw List<Move> return type, whereas the current MoveListFactory<Solution_> contract requires List<? extends Move<Solution_>>, so readers cannot use the snippet as the current interface signature.

    List<Move> createMoveList(Solution_ solution);

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:180

• The sample implementation still takes Random, so it cannot override the current MoveIteratorFactory method that takes RandomGenerator; use RandomGenerator here.

    public Iterator<MyChangeMove> createRandomMoveIterator(ScoreDirector<MyPlanningSolution> scoreDirector,
            Random workingRandom) {

docs/src/modules/ROOT/pages/optimization-algorithms/custom-moves.adoc:1

• Moving these sections out of move-selector-reference.adoc removes the existing customMovesIntroduction, generatingCustomMoves, moveListFactory, and moveIteratorFactory anchors, so existing deep links no longer navigate to their intended content; retain compatibility anchors/stubs or provide redirects to the new page.

[#customMovesIntroduction]

docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• Deleting upgrading-timefold-solver/backwards-compatibility.adoc removes its old URL, so existing bookmarks and external links will 404; add :page-aliases: upgrading-timefold-solver/backwards-compatibility.adoc to this page's document header.

== Backwards compatibility

docs/src/modules/ROOT/pages/upgrading-timefold-solver/overview.adoc:18

• The deleted page also declared [#backwardsCompatibility], but this moved heading does not, so links targeting #backwardsCompatibility lose their anchor; retain that explicit anchor above the heading.

== Backwards compatibility

docs/src/modules/ROOT/pages/upgrading-timefold-solver/upgrade-from-optaplanner.adoc:56

• The page sends readers to the 2.x upgrade recipe at line 17, but this manual recipe says the target is Timefold Solver 1.x and lists Java 17 as the minimum, so current OptaPlanner users can follow the wrong compatibility requirements; update it for 2.x or explicitly separate the 1.x and 2.x paths.

Timefold Solver 1.x is backward compatible with OptaPlanner 8.x,
except for the following changes:

* Java 17 is the minimum, and Java 21 and 25 are also supported.

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite