Configuration

solverforge-cli generated projects have two distinct configuration layers:

• solver.toml - runtime search strategy and termination
• solverforge.app.toml - scaffold metadata and UI contract

They serve different purposes and should be treated differently.

solver.toml: Solver Runtime Configuration

Fresh projects start with a default configuration like this:

[[phases]]
type = "construction_heuristic"
construction_heuristic_type = "first_fit"

[[phases]]
type = "local_search"
[phases.acceptor]
type = "late_acceptance"
late_acceptance_size = 400
[phases.forager]
type = "accepted_count"
limit = 4

[termination]
seconds_spent_limit = 30

This is the user-owned search layer. Edit it directly or use the CLI helpers.

solver.toml should answer operational search questions:

When selector or phase behavior is the question, read the runtime configuration docs and moves docs rather than guessing key names.

Show the Current Config

solverforge config show

Set a Value

solverforge config set termination.seconds_spent_limit 60
solverforge config set environment_mode reproducible

solverforge config set uses dotted key paths and parses values as:

• integer when possible
• float when possible
• boolean for true and false
• string otherwise

That makes it convenient for simple changes, but it does not replace learning the runtime solver.toml model. Use the SolverForge runtime docs when you need deeper phase and move configuration detail.

solverforge.app.toml: Scaffold Metadata and UI Contract

Fresh projects also start with an app spec like this:

[app]
name = "my-scheduler"
starter = "neutral-shell"
shell = "web"
cli_version = "2.2.0"

[runtime]
target = "solverforge 0.15.0"
runtime_source = "crates.io: solverforge 0.15.0"
ui_source = "crates.io: solverforge-ui 0.6.5"

[demo]
default_size = "standard"
available_sizes = ["small", "standard", "large"]

[solution]
name = "Plan"
score = "HardSoftScore"

This example reflects the solverforge-cli 2.2.0 web scaffold target. Fresh web generated apps start on the published solverforge 0.15.0 runtime and the CLI’s solverforge-ui 0.6.5 scaffold target.

Record any later app-owned target changes explicitly in that app’s dependency manifest and solverforge.app.toml.

As you generate facts, entities, variables, constraints, scalar groups, and conflict repairs, the CLI also keeps these structural arrays in sync:

• [[facts]]
• [[entities]]
• [[variables]]
• [[constraints]]
• [[scalar_groups]]
• [[conflict_repairs]]

What the App Spec Is For

solverforge.app.toml is not a second modeling language. It is synchronized metadata used to:

• record scaffold provenance and targets
• record the selected generated shell as web, api, or cli
• store demo defaults
• describe collections and solvable fields for web frontends
• produce static/generated/ui-model.json for web-shell projects

The primary modeling source still lives in:

• src/domain/
• src/constraints/

Manual Edit Guidance

Safe manual edits:

• app name or metadata when you understand the consequences
• demo default size if you want to change the default dataset surfaced by the UI
• app title and labels when you understand how the frontend reads them

Use caution with:

• [[facts]]
• [[entities]]
• [[variables]]
• [[constraints]]
• [[scalar_groups]]
• [[conflict_repairs]]

Those sections are synchronized from the generated code and may be rewritten by future CLI operations.

UI Metadata Files

Two frontend-facing files are derived from the app spec.

static/generated/ui-model.json

This is the generated UI model consumed by static/app.js. It includes:

• entities
• facts
• enabled constraints
• generated views based on scalar or list variables

Scalar and list variables become different view kinds:

• scalar -> kind: "scalar"
• list -> kind: "list"

Do not hand-edit this file. It is generated output.

API and CLI shell projects do not generate static/generated/ui-model.json or the web frontend assets.

static/sf-config.json

This is a lighter config payload for frontend shell labels such as title and subtitle. It is part of the shipped generated shell and stays aligned with the app spec.

Demo Defaults

solverforge generate data --size large does two things:

1. rewrites src/data/data_seed.rs
2. updates [demo].default_size in solverforge.app.toml

That means the selected default dataset is part of the scaffold contract, not just a one-off command flag.

Version Targets and Provenance

Run:

solverforge --version

This reports:

• CLI version
• scaffold runtime target
• scaffold UI target
• scaffold maps target
• source labels for each dependency line

In generated apps, the crate versions are pinned in Cargo.toml, while the app spec records the runtime target label and source. Web-shell apps also record the UI source. The maps dependency is pinned in the web-shell Cargo.toml and surfaced in solverforge --version, but it is not currently duplicated into the app spec’s [runtime] block.

Practical Rule of Thumb

When you are unsure where a change belongs:

• solver behavior and termination -> solver.toml
• domain shape -> src/domain/
• constraint logic -> src/constraints/
• scaffold metadata and derived UI contract -> solverforge.app.toml
• generated frontend views -> static/generated/ui-model.json