PowerSolver 2.0 — Wizard User Guide

Screen-by-screen walkthrough of powersolver-wizard. Eight steps, takes 5–10 minutes for a typical problem.

The wizard lives at https://wizard.planningpowertools.com/. It runs in your browser; it doesn't store data on PowerSolver's servers between sessions (unless you save).

Step 0 — AI Intake (the cornerstone of the AI integration)

Step 0 is the GenAI front door to the whole wizard. Instead of hand-authoring entities, variables, shadows, and constraints across Steps 1–6, you describe your problem in plain business language and PowerAI generates a complete §5bis specification for you. The wizard then loads that spec into Steps 1–7 where you review and refine every field before solving.

It is optional — you can skip it and author manually from Step 1 — but for most users it is the fastest path from "I have a scheduling problem" to "I have a solved schedule".

How it works end-to-end

You answer 5 questions
        │
        ▼
Each answer → PowerAI validates it (HITL) → shows you its interpretation → you confirm
        │
        ▼  (all required answers confirmed)
Click "Generate" → PowerAI runs the generation pipeline
        │              (generation_intent → generation_spec → validate → repair)
        ▼
PowerAI returns a §5bis JSON spec
        │
        ▼
Wizard imports it via importProblem() → Steps 1–7 are pre-filled
        │
        ▼
You review / edit any field, then Solve in Step 7

The 5 intake questions

The intake form asks five qualitative questions. Each builds context for the next — PowerAI sees your earlier confirmed answers when interpreting later ones.

Write naturally. Numbers help ("45 nurses", "50 shifts per week") — PowerAI's validators check that the generated spec contains the counts you stated.

Human-in-the-Loop (HITL) validation

This is the part that makes Step 0 trustworthy. You do not answer all five questions then hope. Instead:

1. You answer one question and click Validate.
2. PowerAI reads your answer (plus all previously-confirmed answers as context) and presents its interpretation back to you — a short summary of what it understood.
3. You either confirm (the answer locks, a green check appears, the next question unlocks) or edit and re-validate.
4. Repeat until all required questions are confirmed.

Questions you haven't reached yet are locked (greyed out). Confirmed answers collapse into compact green cards with an edit pencil — click it to reopen and re-validate any earlier answer.

This means by the time you click Generate, PowerAI has already shown you — and you've already approved — its understanding of every input. No surprises in the generated spec.

Choosing the AI provider and model

A provider/model picker sits near the top of Step 0:

• AI Provider dropdown — lists every provider that has an API key configured in PowerAI Admin (OpenAI, Anthropic, DeepSeek, Groq).
• Model dropdown — the models available for the selected provider; the configured default is marked (default).

If no provider is configured, the picker shows a warning linking to PowerAI Admin. The header badge shows the active provider/model pair once loaded.

You can change provider/model at any point before clicking Generate. The intent-extraction and spec-generation agents both use your selection.

Generate

Once all required questions show green checks, the Generate button enables. Clicking it:

1. Sends your confirmed intake context + chosen model to PowerAI's /ai/generate endpoint.
2. PowerAI runs its multi-agent generation pipeline (intent extraction → spec generation → deterministic schema validation → LLM repair if validation fails).
3. A progress bar tracks the pipeline stages live (streamed via Server-Sent Events).
4. On success, the resulting §5bis JSON is imported into the wizard store — Steps 1–7 are now populated.
5. The wizard advances you to Step 1 so you can review.

Long-running generation and recovery

Generation can take 30–90 seconds depending on model and problem complexity. The wizard handles this gracefully:

• The job id is stored in sessionStorage while generation runs.
• If you close the tab or refresh mid-generation, Step 0 detects the pending job on reload and resumes tracking it (or recovers a completed result). Pending jobs older than 30 minutes are discarded.
• If generation fails, Step 0 shows a clear error and you can retry — your confirmed answers are preserved.

What PowerAI generates

PowerAI's 2.0 prompts emit only the §5bis shape:

• collections with your hosts and entities
• a list variable wiring them together
• the previous + host built-in shadows
• the canonical startTime / endTime derived shadows
• unassigned_count (hard) + minimize_property (soft) constraints

It will never emit 1.x constructs (chained, schedulingPattern: TIME_GRAIN, timeGrainConfig, valueRanges). If the LLM slips, PowerAI's generation_repair agent catches it and corrects before the spec reaches the wizard.

After import — you are still in control

The generated spec is a starting point, not a final answer. Every field lands in Steps 1–7 as editable wizard state:

• Step 1 — the problem type and sequence-mode toggle PowerAI inferred
• Step 2 — the entities it extracted, with their properties
• Step 3 — the hosts and the §5bis sequence configuration
• Step 4 — the constraints it mapped from your rules description
• Steps 5–6 — pinned assignments and solver config
• Step 7 — the full JSON ready to review and Solve

Walk through each step. Adjust anything PowerAI got wrong. The HITL validation makes big misunderstandings rare, but the entity counts, property values, and constraint weights are all worth a human eye before solving.

Returning to Step 0

Click the AI badge / "AI-Assisted Setup" entry in the wizard header to return to Step 0 at any time. Re-running intake replaces the current wizard state — if you've made manual edits in Steps 1–7, export them first (Step 7 → Download) so you don't lose work.

When to skip Step 0

Skip straight to Step 1 and author manually when:

• You already have a §5bis JSON file — use the header's Open button to import it directly.
• Your problem is tiny (2–3 entities) — manual entry is faster than describing it.
• You're iterating on a known problem and only changing a few values.
• No AI provider is configured in PowerAI Admin.

Step 1 — Problem Type

Pick a problem type

The wizard pulls the available problem types from PowerAdmin. Each card represents a domain shape with pre-loaded field definitions for Steps 2 and 3.

Load a plan from Excel

One workbook can hold the whole plan: its lists, its rules and its settings. Step 1 has three buttons:

• Load a plan from Excel reads the workbook. Its Setup sheet sets up the plan (what is planned, what is decided, the reference lists, the settings); a dialog then shows what the workbook holds for steps 2, 3 and 4, with row counts, and offers two ways on:
  • Fill all steps now imports every list and the rules at once and goes to step 7 (Can this work?, then Plan it). It is all or nothing: if any row has a problem, nothing is imported and every problem is listed by sheet, row and column.
  • Go through the steps one by one (e.g. to show and explain each list in a demo): at the top of steps 2, 3 and 4 a banner says what is ready ("Ready in problem.week.xlsx: operations (235). Import"); once imported it says "Imported from …", with Import again.

The step bar marks each step with data waiting in the workbook (spreadsheet icon) and each step imported from it (✓).

• Download workbook template gives the plan you are building as a workbook, or, before you have one, a small worked example (3 jobs, 2 technicians, 2 half-day slots, 5 rules) to replace with your own data.
• ⓘ explains every sheet and every row of the Setup sheet.

The workbook's sheets:

The Setup sheet (columns Part, Name, Label, Decision, Kind, From, Formula):

Decision: Name is the list of its options, Decision its id (used by the rules), Kind resource, time or sequence (items in order on a resource, e.g. a route). Computed value rows are for sequence plans (e.g. arrival times). Every demo has its workbook: powersolver-demos/*/input/*.xlsx (see demos/KITS.md); node powersolver-wizard/tools/make-demo-kit.mjs <problem.json> builds one from any problem — with the same code as the template.

Toggle Sequence Mode

Below the cards, after you pick a type, the Sequence Mode toggle appears:

If you flipped sequence mode ON, Step 3 will show an extra Sequence Configuration card (§ Step 3 below). If you flipped it OFF, Step 3 looks like a plain N-variable picker.

In sequence mode, start times and durations are real date-times and durations on items and hosts, and the sequence's schedule comes from the derived shadows.

Understanding "Consecutive on a host"

This is the setting that turns the wizard from a basic assignment tool ("Task A goes to Alice") into a real scheduler ("Task A goes to Alice from 09:00 to 09:30, then Task B from 09:30 to 10:15"). This subsection walks through what actually happens once you flip it on, using a small example you can paste into the wizard.

What you provide, and what PowerSolver fills in

When you turn on "Consecutive on a host", you describe a small handful of facts:

• The people, vehicles, or crews doing the work. For each one, you give the time their day begins (e.g. Alice starts at 09:00).
• The things being done. For each one, you give how long it takes (e.g. Login API takes 30 minutes).

That's it. You never type a start time for any task — only for the people. So how does the schedule know when each task starts?

PowerSolver fills it in. The moment it decides "Login API goes first on Alice's queue", it can compute:

• Login API's start time = Alice's start-of-day = 09:00.
• Login API's end time = its start + its duration = 09:00 + 30 min = 09:30.

And the moment it decides "Mobile shell goes after Login API on Alice's queue", it can compute:

• Mobile shell's start time = whatever the previous task on Alice's queue ended at = 09:30.
• Mobile shell's end time = 09:30 + 45 min = 10:15.

These auto-computed answers — the task's start time, its end time, the person it landed on, the task right before it in the queue — are called shadow variables. You see them on the Solution and Insights pages. You never enter them; they fall out of the placement PowerSolver chose.

The name "shadow" is meant literally: these values follow the schedule around. The instant PowerSolver moves a task from Alice to Bob, every shadow value attached to that task updates by itself — its host changes, its start time changes, the task before it changes — without you having to do anything.

Two kinds you'll see in Step 3

• The bookkeeping ones — which person is this task on?, which task is right before me? — are called built-in shadows. PowerSolver provides them for free as soon as you turn on "Consecutive on a host". You never write them.
• The two with a formula — startTime and endTime — are called derived shadows. They use the formulas you saw above: previous task's end time (or the person's start-of-day if I'm first), and my start + my duration. Click Apply default template in Step 3 once and both are set. For most scheduling problems you never touch them again.

If your problem needs something exotic — cumulative load along a delivery route, a custom time-window penalty — see Shadow Variables in the Concepts Guide. The wizard's UI for editing custom formulas is intentionally minimal in this release.

Worked example — 3 tasks, 2 developers

The inputs below match the shape of powersolver-template/task-assignment/1-variable.problem.json — you can import that file in the wizard to follow along live.

Tasks:

Developers (both start their working day at 09:00 on 1 June 2026):

One feasible placement the solver might pick:

• Alice's queue: Login API → Mobile shell
• Bob's queue: DB Schema

The shadow values that come out of that placement:

Or as a tiny timeline:

              09:00     09:30           10:15
   Alice      │ Login API │ Mobile shell    │
              09:00              10:00
   Bob        │ DB Schema             │

Every value in the last two columns was computed by the derived shadows — you didn't write a scheduler, you wrote two one-line expressions.

Why order matters

If the solver instead picked Alice's queue: Mobile shell → Login API, the shadows would say:

Same makespan on Alice's queue, but Login API (priority 1 = critical) now starts at 09:45 instead of 09:00. That's why PowerSolver's default soft constraint targets a derived shadow called priorityCost (= position × (C − priority)): order is a real degree of freedom and the constraint guides the solver to put the highest-priority work at position 1 on each queue.

When not to use sequence mode

If your entities have no inherent order or duration — e.g. "assign this lesson to a room", with no back-to-back relationship between lessons — leave Sequence Mode off and use a basic variable instead. Sequence mode is for problems where what comes before me matters.

Step 2 — Entities

The "things being scheduled / assigned". For sequence-mode problems, these are the items that go into host lists (tasks, customer visits, shifts, jobs). For assignment problems, these are the items that get values.

Field grid

Each row is an entity. Columns are pulled from PowerAdmin per problem_type + sequence-mode. Typical columns:

Imports

Upload Excel / CSV, Paste (cells copied from a spreadsheet) or, after Load a plan from Excel, the step's banner Import. The preview shows every column (known field, or new: kept as an extra property rules can use), the first rows, and every problem by row and column; Import stays disabled while any problem remains. Values are read the way the engine reads them: numbers, yes/no, date-times YYYY-MM-DDTHH:MM, lists as comma-separated text, durations as ISO-8601 (PT55M). A column with a name but no value at all (e.g. closed before any closure) is kept, empty, on every row. Import JSON still loads a whole problem file.

Custom properties

Properties not in the PowerAdmin schema for this problem type appear as "custom" rows (different colour). They round-trip in/out of JSON intact — the solver passes them to the supplier expressions and constraint evaluators.

Step 3 — Variables and Value Ranges

Zone 1 — How many variables?

Most problems have ONE variable: a list variable for sequence mode, or a basic variable for assignment. The wizard supports up to four — useful for multi-axis problems (lesson → teacher + timeslot + room).

Zone 2 — Variable config strip

Per variable:

Zone 3 — Sequence Configuration (sequence-mode only)

If you flipped Sequence Mode on in Step 1, this card appears between Zones 2 and 3:

Sequence owner — dropdown listing all variables with assignment type = list. Whichever you pick becomes the host collection. Most problems have just one list variable; auto-selected.

Derived shadows table — currently registered derived shadows on the entity collection. Initially empty.

Apply default template button — seeds the canonical §5bis pair:

{"name": "startTime", "sources": ["previous.endTime", "host.startTime"],
 "expression": "previous?.endTime ?? host.startTime"}
{"name": "endTime",   "sources": ["startTime", "this.duration"],
 "expression": "startTime + this.duration"}

Click this once after Sequence Mode is on. For most problems you don't need to author anything else here — the canonical pair plus the host's startTime property and each entity's duration property cover back-to-back scheduling. What this actually does in practice → see Understanding "Consecutive on a host" in Step 1 for the worked example.

If your problem needs custom expressions (e.g. cumulative load along a vehicle route), edit the JSON directly in Step 7 or send a §5bis request via the API. The wizard's UI for editing custom expressions is intentionally minimal in this release.

Zone 4 — Value grids

Per variable, a card-grid for the value-range items:

• For a list variable, this is the HOST collection (resources, vehicles, crews). At minimum each host needs id + startTime (so the §5bis host.startTime shadow has something to read).
• For a basic variable, this is the value range (employees, rooms, time slots).

Reference lists

Lists the plan reads but does not decide (e.g. Teachers) appear below the decisions, editable like them, with their own Upload / Paste. After Load a plan from Excel, the banner's Import — or Fill all lists from one workbook — fills the items, every decision's options and every reference list at once (a sheet named like each list). What a reference list is, and how it differs from a pin: Concepts guide §5b. A reference list is created when you load a problem or a workbook that has one; there is no "add a reference list" button yet.

Step 4 — Constraints

The wizard's constraint picker offers the 2.0-native rule vocabulary:

"Why don't I see no_conflict / capacity / skill / chain_*?"

Those rules were retired in 2.0. Capacity, time windows, skill matching are now expressed:

• as derived shadows + assertions for value-level checks (test corpus side), or
• by adding new rules to powersolver-api's ConstraintBuilder (development task)

For typical scheduling / routing problems, unassigned_count + minimize_property cover the cases that produce useful, feasible solutions.

Add / edit / delete

Click Add Constraint, pick a rule from the dropdown, fill in params and weight. The wizard validates against the §5bis schema as you type — invalid combos turn the row red with a tooltip.

Import or download rules (Excel)

• Download rules (Excel) writes rules.xlsx: a Rules sheet (one row per rule) and a How to fill sheet that says what each column holds, in your language.
• Import rules (Excel / CSV) — or the banner's Import after Load a plan from Excel — reads a Rules sheet. Columns: Rule (name), Must / Wish, Weight (empty = usual), Kind (the rule as named in this step, e.g. "Capability must match", or its engine id), then one column per setting (variable_field, entity_property, value_property, fields, …, see RULE_REFERENCE.md). Every row is checked against steps 1-3 with the same choices this step's form offers; problems are named by row and column, and nothing is imported while one remains. Import replaces the current rules; each stays editable.

Step 5 — Pinned Assignments (optional)

Fix the decisions of some items in advance; the planner plans the others around them. Use it when the decision is already taken for those items: an operation already running on a machine, exams already sat before a snow day, a meeting that must stay at 10:00. A pinned item still counts for every rule (it occupies its machine, room, slot).

• A pin fixes all decisions of the item (its machine and its slot); you cannot pin only one of them.
• If nobody wants the planner to choose a value for any item (a class keeps its teacher all year), it is not a pin: keep it as item data and a reference list (step 3). See Concepts guide §5b.
• Can this work? (step 7) reports pins that already break a must-follow rule among themselves (PINS_BREAK_RULE).

If you don't need pinning, click Next and the section is omitted from the output JSON.

Step 6 — Solver Config

Construction-heuristic and local-search algorithm choices use Timefold defaults and are not exposed in the wizard. Add explicit choices by editing the JSON in Step 7 if needed.

Step 7 — Check and plan

What you see

• A summary row: type of plan, items, resource lists, rules, fixed in advance, time limit.
• The Can this work? panel, run automatically when the step opens (see below).
• Problem file (JSON) — for experts, with Copy problem file (JSON) and Download.
• Check with AI (optional) and the Plan it button.

Check with AI

Optional. Sends the spec to PowerAI which checks for common authoring mistakes (missing unassigned_count, expression-DSL paths not in sources, properties referenced by minimize_property that don't exist on every entity). Returns advisory hints in the panel below the buttons.

Plan it

Sends the problem to the engine (/api/solve); the request is synchronous and the wizard shows the elapsed time against the time limit. If Can this work? said the problem is impossible, Plan it asks for confirmation first. When the plan is ready:

• the wizard downloads problem_<date-time>.json and solution_<date-time>.json automatically (keep them: they are the record of the plan and the baseline for later comparisons);
• a window shows the score; View solution opens the Results page (verdict, Check before you use it, Overview calendar, Rules & score, all items, Changes, Export to Excel).

Can this work?

When step 7 opens, the problem is checked before planning (POST /api/check, no solving): red — no valid plan is possible, with the reason and the items (e.g. "42 exams need the large halls, 36 places", "the data itself breaks Teacher teaches the subject"); amber — possible, but a resource is nearly full; green — nothing found (not a guarantee). Plan it asks for confirmation when the answer is red. Try a quick plan (20 s) runs a short solve: a plan found proves one exists; none found does not mean impossible. The full list of checks: API_REFERENCE.md (/api/check).

Check before you use it (Results page)

Every message says what is wrong, why it matters and what to do, in plain words and your language. Red: the plan cannot be used (a must-follow rule broken, items not planned, the planner refused the data); amber: allowed but worth a look; grey: information only (e.g. spare capacity) — never a fix to make. A Fix it in step N link appears only when a wizard step can fix it; when the engine refuses the data, the message names the step, the rule and the setting (never a JSON path). In a pipeline run the advice points to the pipeline template instead.

AI assistance throughout the wizard

The wizard has three AI surfaces that all share one model preference. They all talk to PowerAI; the wizard never bundles its own LLM.

Where AI runs in the wizard

Choosing which model answers

Every AI surface shows a compact Model picker (Step 0 has it in full size; the Advisor modal and Critic panel show a smaller two-select version in the header). Provider + model selection persists in localStorage under powersolver.ai.provider / powersolver.ai.model, so the choice survives reloads and is shared between the wizard and the Explain page.

Changing the model while a modal is open re-runs the AI call against the new model. This lets you compare, for example, a fast generalist (deepseek-v4-flash) against a slower reasoning model (deepseek-v4-pro) without having to re-trigger the action. No client-side timeout fires while the slower model is thinking — PowerAI replies when it replies.

If you never touch the picker, the system default configured in PowerAdmin is used.

Limitations — read this once

AI advice is heuristic, not authoritative. The patterns to know:

1. The LLM can be confidently wrong about your domain. It only sees the §5bis JSON we send it. If a task has business significance the JSON doesn't carry (e.g. "API security is a regulatory must-have"), the LLM will treat it as an interchangeable row. Verdicts like "removing this task makes the schedule smoother" are mathematically correct in the abstract — and useless if the task is mandatory in your real world. Treat the AI as a diff explainer, not a domain expert.
2. Output quality scales with model choice. Reasoning models (Anthropic's claude-sonnet, deepseek-pro) produce careful, dependency-aware advice but take 10–30 seconds. Fast models (deepseek-flash, gpt-4o-mini) respond in 2–4 seconds with shallower analysis. The Advisor modal stays open during the wait and shows a spinner; you can hit Proceed anyway before the AI even returns if you're sure.
3. The Critic doesn't know your hard constraints are right. It can detect invariant minimize_property constraints (where the sum is constant for every assignment — no signal to the solver), but it can't know whether you've forgotten to declare a constraint you actually need. Hard constraint design is your responsibility.
4. "Apply & re-solve" rewrites your spec. When you accept a Critic proposal, the spec in sessionStorage is replaced. The previous attempt is preserved in the iteration history — use Restore under Past attempts to roll back to any earlier version.
5. No timeouts by default. A slow response is not a failure. Failures are exception-only (network, parse error). If you want a hard cap, set system.ai.advisor_timeout_ms / system.ai.critic_timeout_ms / system.solver.timeout_ms in PowerAdmin; 0 (default) means no cap.
6. solution_edit_proposal is bounded by the rule vocabulary. PowerSolver's backend only knows unassigned_count and minimize_property. Any proposed edit must fit those — the LLM is instructed to stay inside that vocabulary, but if it strays, the apply step will simply skip the unsupported op.

Configuration knobs

All AI behaviour is tunable from PowerAdmin → System Configuration. No values are hard-coded in the wizard.

Saving the session

The wizard auto-saves state to your browser's localStorage on every step transition. Closing the tab and re-opening it later restores where you left off.

Every plan made with Plan it is kept on Plans (below). The problem and solution files downloaded by Plan it (or Download in step 7) remain a copy you own. To resume from a saved file, click Upload in the left menu and select the problem file; to resume from Excel, use Load a plan from Excel (step 1). The wizard repopulates every step.

1.x saved sessions are rejected by Upload with an explicit error message. There is no auto-conversion. Re-author the problem manually.

Plans

Plans (left menu) lists every plan PowerSolver keeps: name, type, Draft or Solved, number of solutions, best score, who changed it last and when. Plan it stores the plan you are working on (the first time as a new plan, then as an update of the same one) and keeps each solution.

Upload of a problem file and Reset Wizard start a new plan: the next Plan it stores a new one.

Languages

The wizard ships with five locales: English, French, German, Spanish, Dutch. Toggle via the language picker in the header. The Step 1 / Step 3 sequence-mode strings (sequence on/off, "Sequence Configuration", "Apply default template") are translated for en/fr/de; es/nl fall back to English for those strings.

Keyboard shortcuts

Troubleshooting

"This file was authored for PowerSolver 1.x and is no longer supported"

Upload found chained, schedulingPattern, timeGrainConfig, or the v1 entities[]+valueRanges{} split. Re-author through the wizard or use PowerAI's generation_repair against the file.

"Sequence mode is on, but no variable has assignment type list"

In Step 3 Zone 3 you turned Sequence Mode on but every variable in Zone 2 is basic. Change at least one variable's assignment type to list.

"Cannot solve — no constraints defined"

You haven't added any constraints in Step 4. At minimum add a hard unassigned_count for any list variable.

"Solver times out without finding a feasible solution"

Either:

• The problem is genuinely over-constrained (too few hosts, too many entities). Loosen a hard constraint or add hosts.
• The budget is too short. Increase timeoutSeconds in Step 6.
• A derived-shadow expression is producing garbage. Inspect the response — if shadows shows nulls or duplicate values, the expression has a bug.

"Wizard renders but Step 1 has zero problem types"

PowerAdmin is unreachable (its wizard-fields endpoint isn't responding). Check https://admin-api.planningpowertools.com/health.

"Save uploaded a JSON but Step 2 is empty"

The uploaded file's collections doesn't have an entity collection matching the list variable's valueRange. The wizard logs an explicit warning to the browser console — open dev-tools to see which collection key it expected.