-
Notifications
You must be signed in to change notification settings - Fork 0
User Manual
Kotar is an integrated engineering environment for working with SysML v2 and KerML models.
It combines familiar software-development IDE capabilities with model-based systems engineering functionality. Users can author textual SysML v2, work with graphical representations, validate and analyze models, manage engineering files and data, execute scripts and command-line tools, transform external data into model content, and maintain model and workspace revision history.
The Kotar workspace can contain more than the SysML model itself. It can also contain supporting engineering information such as:
- SysML v2 and KerML files;
- Python or TypeScript scripts;
- CSV files;
- configuration files;
- database content;
- transformation scripts;
- generated artifacts;
- other files used as part of the engineering workflow.
This allows Kotar to manage an engineering workspace, rather than treating the SysML model as an isolated artifact.
A workspace is the primary working context in Kotar.
Each workspace contains the files and models associated with a particular project or engineering activity.
Workspaces can be created from sources such as:
- a new project;
- a Git repository;
- a project checked out from a remote SysML v2 service.
Workspaces are isolated from one another, although some persistent database services may be shared.
Typical workspace contents
A workspace may contain:
project/
model/
system.sysml
requirements.sysml
data/
requirements.csv
scripts/
transform.ts
analysis/
analysis.py
.git/
The exact directory structure is up to the user or project.
Many WebIDE tools (including Kotar) automatically use the SysML model in the current workspace as their context.
For example, when using the SysML v2 command-line tools, you normally do not need to explicitly specify every SysML file. The current workspace/model is selected automatically.
The model context can be overridden when a user needs to operate on another directory or subset of the model.
Kotar follows the general interaction model of a modern development IDE.
The primary areas include:
- workspace/file explorer;
- textual editor;
- graphical model editor;
- Problems panel;
- Output panel;
- Debug Console;
- Terminal;
- version-control panel;
- Tables/data interface;
- Flexo/model repository interface;
- advanced Services panel.
Some advanced functionality may be hidden by default so that normal model-authoring workflows remain uncluttered.
In the browser version, files are stored in an emulated virtual filesystem rather than directly in the operating system filesystem.
The browser allocates local storage for the application. This allows Kotar to behave similarly to a desktop IDE while operating in a browser.
Important
Browser storage should not be treated as the only durable backup mechanism.
Browser-managed storage may eventually be removed or evicted. Projects that must be preserved should therefore also be stored using one or more persistent mechanisms such as:
- Git;
- a remote repository;
- a remote SysML v2/Flexo service;
- another supported persistent storage mechanism.
Open a ".sysml" or other supported model file from the workspace explorer. Files can be created within the workspace, uploaded from the desktop by dragging and dropping, retrieved from a remote git or remote Model Management System such as OpenMBEE Flexo.
The textual editor provides language-aware functionality backed by the SysML v2 language tooling.
As the model is edited, Kotar analyzes its syntax and semantics.
Problems discovered in the model are displayed using standard IDE-style severity levels.
See Getting Started for examples.
These include:
- Hint
- Warning
- Error
Problems may originate from:
- syntax errors;
- semantic errors;
- validation rules;
- lint rules;
- transformation state;
- other model analysis.
Use the Problems panel to review detected issues.
Selecting a problem highlights the relevant model location.
Linting identifies modeling constructs that may technically be valid SysML but do not follow recommended modeling practices or project conventions.
See Getting Started for examples.
When a lint problem provides a quick fix:
- Open the problem or the affected model element.
- Select the available quick-fix action.
- Choose the desired scope.
Depending on the rule, Kotar may allow you to:
- fix the selected occurrence;
- fix all occurrences of the same lint rule in the file;
- apply all available automatic lint fixes in the file.
Example
A naming rule may identify:
part def drone_system
and recommend changing it to the naming convention required by the project.
The exact conventions depend on the configured lint rules. Lint rules can be configured in the SysML tab under the "Lint rules" option.
Kotar includes a SysML v2 formatter.
Formatting can be used to normalize textual SysML according to the formatting rules configured for the workspace.
Formatting is also automatically used by some generated-content workflows, including model transformations.
See Getting Started for an example.
Kotar includes a graphical editor for navigating and modifying the SysML model.
Graphical and textual representations operate on the same underlying semantic model.
Users can therefore work with the representation most appropriate for the task.
See Getting Started for examples.
Changes made through one representation can be reflected in the other.
For example:
- modify an element in the graphical editor;
- the corresponding model content changes;
- the textual representation is updated.
The reverse workflow is also supported:
- modify the SysML text;
- the model is re-evaluated;
- the graphical representation reflects the changed model.
- Preserving graphical identity and layout across certain textual operations remains an area under development.
Moving, cutting, pasting, or restructuring textual model elements can make it difficult to determine whether an element is:
- the same semantic element moved to another location; or
- a newly created element.
This may affect graphical layout.
- Users should take care with unnamed elements created graphically.
The semantic model can contain elements with identities that cannot always be represented unambiguously in the textual notation.
This is particularly relevant to graphical relationships involving unnamed model elements.
Recommendation: Prefer named model elements where practical when the model must be edited interchangeably through graphical and textual representations.
See See Known Issues for more information.
Kotar provides model-aware engineering analysis rather than limiting model checking to syntax.
One important capability is constraint propagation.
Constraint propagation determines information that follows logically from the constraints in the model.
For example, suppose a model constrains:
airframeMass + batteryMass < 1.8 kg
Even if "airframeMass" does not yet have one fixed value, Kotar may be able to infer a range within which it must fall.
Such an inferred range is not the same as assigning a value. It represents something that must be true for models satisfying the applicable constraints.
Constraint and requirement analysis may produce several kinds of result.
Depending on the analysis, a condition may be:
- satisfied;
- violated;
- undecided;
- constrained to an inferred range.
Where available, the UI may also expose the reasoning or constraint responsible for a result.
A blank or undecided result should not automatically be interpreted as success.
Some constraints require more advanced mathematical reasoning.
The Kotar architecture supports use of an SMT solver such as Z3 for these cases.
An SMT solver can determine whether a collection of constraints is:
- satisfiable;
- unsatisfiable;
and may provide a witness assignment showing a set of values that satisfies the constraints.
Example
A result might state that a model is satisfiable when:
duty = 0
Such a value is a witness demonstrating one solution; it does not necessarily mean that it is the only possible solution.
Availability
Z3 is not available in the running build.
Kotar contains an interactive REPL for evaluating expressions.
The REPL can be used to evaluate KerML/SysML expressions without creating a separate script.
The result is printed interactively.
The REPL is useful for:
- exploring model expressions;
- testing calculations;
- experimenting with model queries;
- investigating model behavior.
Kotar includes a browser-based terminal.
The terminal is intended primarily for advanced users, developers, automation authors, and scripted workflows.
It provides a shell-like environment that supports Bash-style expressions and scripts.
Capabilities demonstrated or discussed include:
- Bash scripting;
- filesystem operations;
- "curl"-style HTTP requests;
- JSON processing;
- compression utilities;
- encoding/decoding utilities;
- SysML v2 command-line tools.
Use the terminal's "help" command to see the command-line programs available in the current distribution.
The Kotar terminal provides access to the SysML v2 CLI.
Because the current workspace is normally automatically selected as the model context, CLI commands can work against the loaded model without requiring every source file to be provided manually.
The CLI capabilities shown during the demo included:
| Capability | Purpose |
|---|---|
| Contextual JSON | Convert model content to contextual/interchange JSON |
| Semantic diff | Compare models at the semantic level |
| Format | Format textual SysML |
| Validate | Detect model validation errors |
| Lint | Apply model linting rules |
| Verify | Verify requirements and constraints |
| Evaluate | Evaluate KerML/SysML expressions |
| Query | Query model content |
| Inspect | Inspect elements, metaclasses, owners, and members |
| Parse / AST | Parse model content and inspect the syntax tree |
| PlantUML | Emit PlantUML-based diagram information |
| Refactor | Perform model-aware refactoring operations |
The CLI is primarily an advanced-user capability. Most normal model-authoring workflows can be performed directly through the graphical or textual Kotar interfaces.
Under the hood Kotar runs several engineering services locally including:
- SysML v2 service
- Flexo/MMS
- RDF Quad Store
- SQLite3
The Services panel can be used to check on the running services but is considered an advanced feature that most users will not interact with.
Open the Services panel to inspect logs from the local services.
This can be useful for:
- development;
- debugging;
- investigating API interactions;
- diagnosing repository or model-service problems.
The Services interface also allows HTTP requests to be sent directly to the services. This is similar to using a Swagger/OpenAPI interface.
This feature is intended primarily for developers and advanced users. Normal users are recommended to access model functionality through the higher-level Kotar interface rather than interacting directly with MMS.
Kotar integrates with Flexo/MMS for model persistence and model revision management.
MMS operates beneath the SysML v2 service. Normal users generally interact with the SysML v2 service or Kotar facade rather than using the MMS API directly.
The Flexo interface can be used to inspect model repository information such as:
- projects;
- commits;
- model revisions;
- model deltas.
Remote Flexo instances can also be configured through this interface.
A remote Flexo/SysML v2 service can be connected to Kotar.
Once connected, available projects can be enumerated and a remote project can be checked out as a local workspace.
A typical workflow is:
- configure the remote service;
- select a remote project;
- check out the project;
- work locally in a Kotar workspace;
- synchronize or commit model changes according to the configured workflow.
-
Open the Flexo panel. In the bottom panel, click the FLEXO tab (next to Problems). The built-in Mesh SysMLv2 connection is active by default.
-
Go to Manage connections. Click the connection dropdown (showing "Mesh SysMLv2 /svc/sysmlv2") and choose Manage connections…. This lists the two built-in connections, Mesh MMS and Mesh SysMLv2. Neither can be edited.
-
Open settings.json. Click Open settings.json in the top right of the Connections view. This opens your User settings file in the editor.
-
Add a
sysmlv2.flexo.connectionsblock. It accepts MMS and SysMLv2 connections in the following format.
"sysmlv2.flexo.connections": [
{
"name": "<connection-name>",
"kind": "mms",
"url": "<mms-url>",
"token": "<your-token>",
"readOnly": true
},
{
"name": "<connection-name>",
"kind": "sysmlv2",
"url": "<sysmlv2-url>",
"token": "<your-token>",
"mms": "<mms-connection-name>"
}
]Do not include the "Bearer " prefix with your token.
-
Save the file.
-
Select the new connection. Go back to the Flexo tab, pick your connection from the dropdown, and confirm your projects load.
-
Right click a project and select "Clone"
Check out this page from OpenMBEE if you are interesting in using the public remote flexo.
The + Add connection form has the same fields: Name, Kind (MMS or SysMLv2), URL, Token, History limit (MMS only), linked MMS (SysMLv2 only), a Read-only checkbox, and a User vs. Workspace settings layer.
Kotar includes a graphical Tables interface backed by SQLite.
The table database is a general engineering-data capability. It is not itself the SysML model.
Users can:
- create a database;
- create a table;
- inspect data;
- edit cells;
- run SQL.
This allows users to develop complex engineering workflows.
CSV files can be viewed through a table-oriented user interface.
This is useful when engineering source information is naturally represented in tabular form, such as:
- requirements;
- parameter sets;
- interface data;
- test data;
- engineering inventories
Kotar can load the selected tabular data in the local SQLite database and can assist in creating filters.
For example: in a requirements CSV, Kotar can recognize repeated category values and present them as enum-like choices.
Selecting a value generates the corresponding textual filter expression interactively.
After filtering a data set, the resulting view can be used for additional operations such as:
- export to other formats
- loading the filtered data into a new SQL table
Current limitation
Some advanced table operations are still in development.
Kotar supports transformation of external engineering data into SysML v2 model content.
One demonstrated example transformed requirements contained in a CSV file into SysML requirement elements.
Transformations are useful when authoritative engineering information originates outside the SysML model.
Possible source information includes:
- CSV;
- SQL tables;
- other structured engineering data sources.
The demonstrated workflow included creating a Transform Pipeline.
The transformation can be implemented using TypeScript; Python was also discussed as a desired language option.
A transformation can specify information such as:
- transformation source;
- target package;
- generated model content;
- optional templates.
The transcript does not establish the exact final UI labels for every field, so those names should be confirmed against the production build.
When working with a TypeScript transformation, Kotar provides a model-aware TypeScript environment.
A global "transform" object is made available to transformation scripts.
Kotar also creates contextual TypeScript configuration and virtual type-definition files.
These include:
"model.d.ts"
Provides type information representing the current model.
Transform definitions
Provide typed representations of available engineering data sources.
As a result, TypeScript autocomplete and type checking can understand both the model and the source engineering data.
The TypeScript transformation used a recognized transformer file and default export.
When the transformer is run, Kotar:
- opens the debug/output environment;
- executes the transformation;
- generates a summary;
- generates SysML model content;
- applies the workspace formatter;
- applies lint rules;
- reports any lint warnings;
- stages the resulting model changes as a diff.
This allows generated changes to be inspected before becoming part of the accepted model.
Generated model changes are presented for review.
Before applying a transformation result:
- inspect the generated summary;
- review the model diff;
- review validation/lint findings;
- verify that the generated elements are appropriate;
- accept or reject the proposed changes.
Current implementation note
The transformation staging/rejection mechanism as an area requiring additional tests and guardrails.
Users should therefore review transformation results carefully.
Elements created through a transformation are visually distinguished from manually authored model content.
Generated requirements were displayed using different coloring.
Hovering over a generated element displayed information equivalent to:
«Generated from "requirements.csv" by the transformation script. Edit the data, not the model.»
This is intended to prevent divergence between:
- authoritative source data; and
- generated SysML model content.
Kotar records provenance for generated model elements.
There is an included a companion provenance file.
Provenance information links generated model content to:
- the transformation;
- the source file;
- a digest/version of that source;
- the generated model elements.
This allows Kotar to identify where generated content came from and whether the source or transformer has changed.
When authoritative source data changes:
- edit the source data, for example "requirements.csv";
- rerun the transformer;
- review the generated summary and diff;
- accept the appropriate model changes.
Do not manually modify generated model content when the source data should remain authoritative.
Kotar can detect when a transformation has changed since model content was generated.
This condition appeared in the Problems interface.
This helps prevent users from assuming that generated model content is up to date when either:
- its source has changed; or
- the transformation logic has changed.
Kotar maintains automatic revision history.
Changes to workspace files generate revisions without requiring the user to explicitly create a commit every time.
The revision system tracks the engineering workspace, not only SysML files.
It may therefore include:
- model files;
- scripts;
- CSV files;
- configuration;
- other workspace artifacts.
Text files are represented using textual changes, while binary files require different revision handling.
The workspace can also be managed as a Git repository.
A typical workflow is:
- initialize Git for the workspace;
- create an initial commit;
- continue working normally;
- allow Kotar to maintain fine-grained automatic revisions;
- create intentional Git commits as meaningful engineering checkpoints.
Creating a Git commit promotes that workspace state to an anchored human checkpoint. Fine-grained autosave revisions around that checkpoint may then be coalesced while retaining recoverability.
When both Git and Flexo are used, a Git commit can be associated with the corresponding model commit.
This creates traceability between:
- the complete engineering workspace in Git; and
- the corresponding SysML model state in Flexo.
The Git commit is being associated with the Flexo commit.
The revision system and Git solve different problems.
Automatic revisions
Provide fine-grained history while you work.
Git commits
Represent deliberate human checkpoints with commit messages and support normal Git workflows.
Flexo commits
Represent model repository states and can be associated with Git checkpoints.
Users therefore do not need to create a Git commit for every small edit.
Normal editor Undo is separate from the workspace revision-history system.
Using "Ctrl+Z", for example, performs an editor undo operation.
Revision history records workspace states and deltas separately.
Use:
- Undo for immediate local editing mistakes;
- Revision History when you need to inspect or restore an earlier workspace state.
Kotar uses a non-destructive recovery mechanism.
When you restore an earlier state:
- the current state is preserved;
- Kotar computes the difference between the current state and the selected previous revision;
- that change is applied;
- the restoration becomes a new revision.
Nothing later in the history is deleted.
This approach is referred to as “always forward.”
Fine-grained KotarE revisions can also be represented in a private shadow tree in Git.
The shadow tree corresponds to automatic Kotar revisions.
It can optionally be pushed to a remote Git repository using a separate name, allowing the automatic Kotar revision history to be persisted remotely as well.
This is an advanced capability.
Most users can simply work with the normal revision-history interface.
Git can contain intermediate engineering work, including incomplete model states.
Flexo can be configured or used more conservatively as the location for valid or authoritative model states.
The current implementation already commits automatic model revisions to Flexo only when the model is valid. The discussion proposed extending this with additional gates.
Possible gates include:
- successful parsing;
- model validity;
- validation rules;
- constraint checks;
- project-specific quality policies.
This allows users to continue version-controlling incomplete work in Git while keeping the authoritative model repository healthy.
Kotar is intended to support users who need to combine modeling with engineering automation.
An advanced workflow might therefore include:
External engineering data
↓
CSV / SQL
↓
TypeScript or Python analysis/transformation
↓
Generated SysML
↓
Validation / linting
↓
Review generated diff
↓
Accept model changes
↓
Commit workspace to Git
↓
Commit valid model state to Flexo
Kotar provides these capabilities within one workspace so that the associated artifacts can remain traceable.
For normal engineering work, the following workflow is recommended.
Step 1 — Open or create a workspace
Create a project, clone a Git repository, or check out a project from the SysML v2 service.
Step 2 — Edit the model
Use either:
- textual SysML editing; or
- graphical modeling.
Step 3 — Resolve problems
Review:
- errors;
- warnings;
- hints;
- lint findings.
Apply quick fixes where appropriate.
Step 4 — Review analysis
Where relevant, review:
- requirement verification;
- constraint results;
- inferred ranges;
- solver findings.
Do not interpret an undecided result as a successful verification.
Step 5 — Integrate engineering data
If model information originates in CSV, SQL, or another structured source, use a transformation rather than manually duplicating the information.
Step 6 — Review generated changes
Inspect:
- transformation summary;
- model diff;
- validation;
- lint results;
- provenance.
Step 7 — Create a Git checkpoint
When the workspace reaches a meaningful state, create a Git commit.
Step 8 — Promote valid model states
Synchronize valid model states with Flexo according to the project's model-management policy.
Preserve the complete engineering workspace
Do not version only the SysML model if scripts, CSV files, or transformations are necessary to understand or reproduce it.
Git should normally contain the entire engineering workspace.
Keep authoritative source information authoritative
If a model element is generated from another source, modify the source and regenerate the model rather than editing the generated element manually.
Use meaningful Git checkpoints
Allow automatic revisions to capture small changes.
Use Git commits for intentional engineering milestones.
Review generated content
Transformation output should be treated like generated code:
- inspect it;
- validate it;
- review its diff;
- confirm its provenance.
Name model elements when practical
Named elements provide more reliable synchronization between textual and graphical representations than unnamed elements.
Do not rely solely on browser storage
Use Git, Flexo, or another persistent repository for important projects.
Understand verification results
Distinguish between:
- a concrete evaluated value;
- an inferred constraint or range;
- satisfiability;
- a witness value;
- an undecided result.
These represent different engineering conclusions.
The following features are intended primarily for advanced users:
| Feature | Typical User |
|---|---|
| Terminal | Automation developer / power user |
| SysML CLI | Advanced modeler / developer |
| REPL | Analyst / developer |
| Services panel | Developer / administrator |
| Direct HTTP calls | Integration developer |
| Flexo/MMS internals | Model repository administrator |
| Transformation scripting | Automation/model integration developer |
| SQL database | Analyst / integration developer |
| Shadow Git history | Configuration-management expert |
Most everyday SysML modeling does not require direct interaction with these capabilities.
Graphical/textual identity preservation
Certain textual restructuring operations may interfere with graphical layout or element identity.
Unnamed graphical elements
Not every semantic relationship involving unnamed elements has an equivalent textual representation.
Solver availability
Z3-based analysis may not be available in every build.
Transformation staging
Apply/reject workflows require additional hardening and testing.
Table projection
Conveniently hiding/projecting columns while transferring data between table schemas was discussed but was not implemented in the demonstrated version.
Real-time collaboration
CRDT-based multi-user editing was discussed as a future architecture but was not demonstrated as an available user capability.
Package dependency manifests
A formal project/package dependency manifest comparable to software package-management systems was discussed but was explicitly identified as not yet implemented.
| Area | Key Capabilities |
|---|---|
| Modeling | Textual SysML v2/KerML and graphical modeling |
| IDE assistance | Diagnostics, linting, formatting, quick fixes |
| Analysis | Evaluation, requirement verification, constraint propagation |
| Solver | SMT/Z3-based reasoning where available |
| Data | CSV views, filters, SQLite tables and SQL |
| Transformation | Typed transformation scripts, generated SysML, provenance |
| CLI | Model conversion, query, validation, diff, formatting and analysis |
| Scripting | Terminal, Bash-style scripting, REPL, TypeScript; Python integration discussed |
| Repository | Local/remote SysML v2 and Flexo/MMS |
| Version control | Autosave revisions, Git and Flexo association |
| Recovery | Non-destructive rollback and shadow revision history |
| Services | Local SysML v2, MMS, RDF and SQLite services |
| Integration | Direct HTTP/API access for advanced users |
Workspace The complete set of model files, data, scripts, and other files associated with an engineering project.
Revision A fine-grained automatically recorded change to the workspace.
Git Commit A deliberate workspace checkpoint stored through Git.
Flexo Commit A model repository revision representing a SysML model state.
Model Context The SysML model currently loaded and used implicitly by Kotar tooling.
Lint A modeling-quality rule that may identify questionable but syntactically valid constructs.
Constraint Propagation Inference of values or ranges that follow from the model's constraints.
Witness Assignment One set of values demonstrating that a constraint system can be satisfied.
Transformation A programmatic process for converting external engineering information into SysML model content.
Provenance Metadata identifying the source and transformation responsible for generated model content.
Generated Element A SysML model element produced from another engineering source rather than manually authored.
MMS The model-management layer beneath the SysML v2 service in the demonstrated architecture.
Shadow History A Git-backed representation of Kotar's fine-grained automatic revision history.
Kotar provides modeling, validation, transformation, and analysis capabilities intended to assist systems engineering work.
Users remain responsible for reviewing model content and analysis results and for applying the engineering verification, validation, review, and certification processes appropriate to their project.
A successful parse, validation, transformation, or constraint result should not by itself be interpreted as certification that an engineered system is correct, complete, safe, or suitable for a particular application.
Starforge Kotar Documentation · Copyright © 2026 Planetary Utilities, Corp.
For support, use the repository's GitHub Issues.
Do not submit confidential, proprietary, export-controlled, classified, or customer-sensitive information.
Documentation
Help
Releases