How-to roadmap
Use this page when you already know the job you want pyfcstm to perform and need a task recipe rather than a learning tour. The global sidebar lists every how-to page directly; this roadmap helps you choose the right sibling task page, prepare the correct input, and know which reference or explanation page to open when a recipe deliberately stops.
Role: this page is the How-to router for repeatable tasks. It turns user goals such as install, inspect, simulate, generate, visualize, author templates, or maintain grammar assets into the page that owns the recipe.
Non-goals: this page is not a tutorial, not a design explanation, not a CLI reference, and not a full schema table. It does not replace the task pages it links to; it only tells you which one to use and what success signal to expect.
What a how-to guide promises
A how-to guide should start from a concrete assumption, give ordered steps, show a short output or success signal, name common mistakes, and link away to reference facts when the command or option list becomes too broad. If a page only explains why behavior exists, it belongs under Explanation map. If a page primarily lists exact forms and fields, it belongs under Reference map.
New-user path
If you just finished a tutorial, choose the how-to page that repeats the task in a less guided way.
After the quick start, use CLI workflows to repeat the command sequence with your own file.
After the DSL tutorial, use DSL task guide when changing model structure.
After the simulation or inspect tutorial, use Simulation tasks or Inspect tasks for repeatable troubleshooting tasks.
After generation or visualization tutorials, use Generation tasks, Template author tasks, or Visualization tasks depending on whether you need output files, template authoring, or diagrams.
Experienced-user path
If you already know the feature area, start from the task verb.
Need to prepare an environment or CI job: open Install pyfcstm.
Need a command chain: open CLI workflows.
Need to change source language content: open DSL task guide.
Need runtime behavior: open Simulation tasks.
Need structure, diagnostics, or LLM repair feedback: open Inspect tasks.
Need generated code or templates: open Generation tasks or Template author tasks.
Need diagrams or grammar/editor maintenance: open Visualization tasks or Grammar and editor tasks.
Maintainer path
Use this route to review how-to quality.
Check each task has prerequisites, steps, success signal, failure boundary, and next links.
Check examples are short and purpose-tied; long workflows should live in generated demo resources rather than in prose.
Check task recipes do not silently become reference dumps.
Check changed Chinese pages carry the same task, output, warning, and next-link coverage as the English page.
Task page usage signals
A good task page should tell readers what input they need before they start and what observable signal means the task succeeded after they finish. Command tasks usually need a short output excerpt, generated filename, or exit behavior. Editing tasks usually need to say which file should change, how to check the result, and how to repair common mistakes.
If a task page only says “run this command” without a success signal, it is not yet verifiable enough. If it starts explaining broad design reasons, move that reasoning to an explanation page. If it lists a closed set of options, move the exact facts to a reference page.
A task page may stay concise, but every step should leave enough evidence for a reader or reviewer to reproduce the outcome.
Task cards
Installation: Install pyfcstm
Prerequisites: you need a Python environment, a package source, or a CI image where pyfcstm should become available.
Outcome: you can install from PyPI or the main branch, verify the Python package, verify the CLI, and decide which optional renderer or native toolchain checks are outside the core install.
Non-goal: it does not teach every command workflow, DSL construct, or generated runtime behavior.
Next step: after installation, run CLI workflows or return to Quick Start for the first end-to-end path.
CLI workflows: CLI workflows
Prerequisites: the pyfcstm command is installed and you have an input
.fcstm file or are ready to copy the small sample in the guide.
Outcome: you can choose between simulate, inspect, generate,
plantuml, and visualize workflows and recognize the success signal for
each command family.
Non-goal: it does not list every option, alias, stdout/stderr boundary, or exit status fact.
Next step: use CLI reference for command facts and the feature specific how-to page when a workflow becomes deep.
BMC tasks: BMC Task Recipes
Prerequisites: you have an FCSTM model, know the bounded question to ask, and
can create one .fbmcq file.
Outcome: you can run all seven property kinds, choose initial state and assumptions, filter abstract calls, gate CI with JSON and exit status, diagnose timeout or incomplete horizons, and distinguish property failure from replay failure.
Non-goal: it does not define every grammar production, JSON field, or mathematical objective.
Next step: query facts live in FBMCQ Language Reference, result and CLI facts in BMC CLI and Result Protocol Reference, and the derivation starts at How FCSTM Becomes a Bounded Transition System.
DSL tasks: DSL task guide
Prerequisites: you are editing an FCSTM model and know whether you are changing states, transitions, events, guards, effects, lifecycle actions, or imports.
Outcome: you can perform common authoring tasks such as adding states, writing event scopes, guarding transitions, using lifecycle hooks, and choosing forced or combo forms safely.
Non-goal: it does not provide every grammar production, every invalid form, or the full semantic reasoning behind expansion.
Next step: use DSL reference for exact syntax and DSL semantics explanation when a form’s meaning is not obvious.
Simulation tasks: Simulation tasks
Prerequisites: your model parses and you want to execute cycles, events, hot starts, abstract handlers, or history export.
Outcome: you can run batch commands, use the interactive REPL, inject events, hot start at a state, implement abstract handlers, and debug a failing model.
Non-goal: it does not explain the full execution-order model or list every API field in isolation.
Next step: use Execution semantics explanation for behavior reasoning and Simulation reference for exact command/API facts.
Inspect tasks: Inspect tasks
Prerequisites: you have an FCSTM file and need a human report, JSON output, an LLM-oriented repair report, or a CI severity gate.
Outcome: you can choose report formats, save color-controlled human output, write full JSON, fail a CI gate from severity, and navigate from diagnostics to source spans.
Non-goal: it does not define every JSON field, every diagnostic code, or every static-analysis limitation inline.
Next step: use Inspect report reference for report fields, Diagnostics code reference for codes, and Diagnostics explanation for diagnostic boundaries.
Generation tasks: Generation tasks
Prerequisites: your model parses and you need generated artifacts from a packaged built-in template or a custom template directory.
Outcome: you can choose --template versus --template-dir, clear output
safely, generate each built-in family, read generated README files, and
smoke-check relevant outputs.
Non-goal: it does not teach template internals in full or make native toolchain checks automatic.
Next step: use Template author tasks for template authoring, Built-in templates reference for built-in target contracts, and Template configuration reference for config keys.
Visualization tasks: Visualization tasks
Prerequisites: you have a model and need PlantUML source, rendered output, detail presets, focused views, CI-stable diagram jobs, or Python API control.
Outcome: you can choose source versus rendered output, compare presets, render a final artifact, and keep diagram jobs stable in headless environments.
Non-goal: it does not enumerate every visualization option or backend failure in the task flow.
Next step: use Visualization options reference for exact fields and First diagram if you need a first diagram path.
Grammar and editor tasks: Grammar and editor tasks
Prerequisites: you are changing syntax, highlighting, VSCode assets, the prompt facing grammar guide, or validation suites.
Outcome: you can decide what kind of grammar change you are making, regenerate ANTLR artifacts, synchronize Pygments and TextMate highlighting, and verify the editor extension assets.
Non-goal: it does not explain every parser/model boundary or replace the exact file and command reference.
Next step: use Grammar and editor tooling reference for canonical files and Grammar tooling explanation for why one syntax change touches multiple layers.
How to leave the how-to area
After a task succeeds, use Reference when you need precise facts, Explanations when behavior surprises you, and Tutorials when you need a smaller learning path for another teammate. A how-to page should make that exit obvious instead of trying to become every other role at once.