# ASysT — User Documentation

Welcome! **ASysT** creates, edits and shows your **SysML v2** (`.sysml`) models as live, arrangeable
diagrams in a local browser app launched from VS Code. Nothing is uploaded anywhere, and ASysT brings
its language server and engine with it.

This folder is the **user manual**. Read it in order if you're new, or jump to a topic.

| # | Guide | What it covers |
|---|-------|----------------|
| 1 | [Getting started](01_Getting_started.md) | Install the extension, open your first model, read the diagram |
| 2 | [Navigating models](02_Navigating_models.md) | The canvas, the Explorer, scope, internal structure, search, saved layouts |
| 3 | [Diagrams & views](03_Diagrams_and_views.md) | The diagram kinds, viewpoints/filters, renderings, presets |
| 4 | [Checking your model](04_Validation.md) | The Problems panel, what parser diagnostics do and do not prove, scripting a gate |
| 5 | [Variant management](05_Variant_management.md) | Product-line models: configure a 150 % model into a single product |
| 6 | [Exporting & reports](06_Export_and_reports.md) | Export a diagram (SVG/PNG/PDF), publish a shareable report, archive a baseline |
| 7 | [API reference](07_API_reference.md) | For power users: scripting the engine over HTTP (export, validate, search…) |
| — | [Release notes](ReleaseNotes/README.md) | What changed in each version |

---

## What ASysT is — and how it protects the model

ASysT is a **viewer and layouter with a validated Pre-alpha Modeler**. The `.sysml` text remains the
canonical model.

- **You can try modeling visually or work as text.** The Pre-alpha Modeler can create a model and apply
  supported element/relation drafts in
  ASysT, edit an exact declaration from a Source Card, or use VS Code directly.
- **Explicit source changes are fenced.** ASysT checks one expected whole-model revision, applies concrete
  ranges across all affected files, asks the bundled language server for whole-model diagnostics, then
  publishes the complete file set atomically. Failed or conflicting edits leave every original unchanged;
  source undo/redo is separate from layout history. A quiet parser is not a proof of semantic correctness.
- **Presentation remains separate.** Graph/tree arrangement, table filter/sort and sequence pan/zoom stay
  in `Rendering/*.asystrendering`; variant configurations stay in `*.variants.yaml`.
- **Git remains the durable history.** Review and recover the plain-text model with the same workflow as code.

That's the whole bet: keep the model as text you own while making both *modeling* and *seeing* it excellent.

## The 30-second tour

1. Click the permanent **ASysT icon in VS Code's left Activity Bar** and choose the bundled pilot or a
   `.sysml`/`.kerml` file. The icon is present even before you have a model.
2. If a model is already open, **ASysT: Open in Browser** at the top-right of its editor is the direct
   shortcut — the diagram opens in your browser.
3. **Drag the boxes** to arrange them; your arrangement is remembered.
4. Open the **Modeler** drawer to create supported model facts. Each completed gesture is validated and
   written before the next begins; there is no semantic Save button.
5. **Right-click** a box or named relation; its Source Card can reveal/copy the declaration, edit or delete
   it, break the relation, and undo/redo source transactions.
6. Select a source-backed element to use the syntax-coloured **source pane** on the right. It accepts text
   edits, shows a debounced live check, and writes only when you press its Save control or `Ctrl+S`. A
   refusal keeps every typed character and states the engine's reason.
7. Use the toolbar to **search** and **Export**; the **Problems** badge sits bottom-left, **Variants**
   appears when applicable, and the drawing tools control layout, display, frame and legend.

Each of those is a guide above. Start with [Getting started](01_Getting_started.md).
