Workspaces and Projects

What This Chapter Covers

This chapter explains the two units PAIO uses to hold your work — the workspace and the project. It covers how to open a workspace, how to create, rename, and delete a project, every operation available in the project Explorer, the save commands, and the edit History panel. It is written for users starting their first design in PAIO. You need a login and an active license (03. Installation, Login and License); while a license is expired, every create, delete, rename, and save described in this chapter is blocked.

---

4.1 Concepts

PAIO organizes work into two layers.

Workspace (a single folder)
 ├── ProjectA/          ← project
 │    ├── design/  doc/  code/  workflow/  export/  import/
 ├── ProjectB/          ← project
 └── ...

• Workspace: the parent folder that holds projects. The app opens one workspace at a time.
• Project: one set of design artifacts. A project has a project metadata file and six fixed folders.

Only the folders directly under the workspace are examined as project candidates, and only a folder that has a metadata file is recognized as a project. Projects nested deeper are not found. The project name shown in the Explorer comes from the metadata file, not from the folder name, and the list is sorted by name.

You can open and edit several projects from one workspace at the same time. When you do, Undo/Redo and Save All apply only to the project that owns the active tab. This keeps one project's edit history out of another's. The one exception is app shutdown, which saves the unsaved edits of every project.

Note that launching PAIO a second time from the same working directory does not open a new window; it brings the existing window to the front.

---

4.2 Opening a Workspace

1. Run Project ▸ Open Workspace... (Ctrl+O). An OS folder picker titled Select Workspace Folder opens. You can also create a new folder from this picker.
2. Select a folder. The app scans the level directly below it for projects and lists them in the Explorer.
3. The sidebar title changes to EXPLORER: <folder name>. If you are connected to a remote, the connection information appears in the title as well ([SSH: <host>], [WSL: <distribution>], [Container: <container>]). Remote connections are covered in 17. Remote Development (SSH, Dev Container, WSL).

Check your work: if the workspace holds at least one project, the projects appear in the tree. If it holds none, PAIO shows No projects in workspace and Create a new project to get started, together with a New Project button. If you have not opened a workspace yet, PAIO shows No workspace open and Open a workspace to get started, together with an Open Folder button.

• The last workspace you opened is remembered and restored automatically on the next launch.
• PAIO watches the workspace folder, so files added or deleted outside the app are reflected in the Explorer automatically (4.10).
• A local workspace shows projects only. Folders and files in the workspace folder that are not projects do not appear in the tree. Remote modes (SSH/WSL/container) do the opposite: they show the entire folder contents and draw the projects inside as project nodes.
• Changing the workspace clears the entire edit history (4.9).

---

4.3 Creating a Project

4.3.1 Procedure

1. Run Project ▸ New Project (Ctrl+N). You can also right-click empty space in the Explorer, or the workspace node, and choose New Project.
2. If no workspace is open, the workspace picker appears first. Canceling it also cancels project creation.
3. Enter a name in the New Project dialog. The prompt reads Enter a name for the new project: and the confirm button is Create.
4. The name is checked the moment you click Create or press Enter. If it breaks a rule, the matching message from 4.3.2 appears below the field and the dialog stays open. The Create button itself is never disabled, and the message disappears once you correct the name.

Check your work: a new project node appears in the tree, and expanding it shows the fixed folders. Open the System node under design and you find an empty system named System.

4.3.2 Name Rules

A project name must follow these rules. Breaking one shows the message listed beside it.

Rule	Message on violation
Cannot be empty	Project name cannot be empty
Letters, digits, hyphens, and underscores only	Project name can only contain letters, numbers, hyphens, and underscores
No Windows reserved names (CON, PRN, AUX, NUL, COM0 – COM9, LPT0 – LPT9)	"<name>" is a reserved system name and cannot be used
No duplicates within the workspace (case-insensitive)	Project "<name>" already exists

The reserved-name check ignores case, just as the duplicate check does. Names that differ only in case, such as Con or com1, are rejected too.

For example, DoorEcu, body-domain, and QuickStart_01 are accepted, while a name with spaces or a dot, such as Door Ecu or door.ecu, is rejected, and so is any name containing non-ASCII letters.

4.3.3 What Gets Created

Creating a project produces the following.

Item	Contents
Six fixed folders	doc, design, code, workflow, export, import
Three default models	System · VFB · IVC

The default models start with this content.

• System — both the system name and the root composition name are System. Neither follows the project name, and you can change both freely later.
• VFB — a single root composition named System, empty inside.
• IVC — ECUs, HPCs, communication clusters, and coupling elements are all empty.

Existing folders and models are never overwritten. If the folders exist but the metadata file is missing, PAIO creates a new metadata file and recovers the folder as a project. If both the folders and the metadata file exist, creation stops with the error Project "<name>" already exists.

4.3.4 Quick Start Projects

Project ▸ Quick Start creates a project the same way. Three things differ.

• The dialog title is Quick Start and the prompt reads Enter a name for the new Quick Start project:.
• The dialog suggests a default name in the form QuickStart_01. PAIO scans the QuickStart_NN names already in the workspace and picks the lowest free number, padded to two digits.
• The QuickStart editor opens in gallery mode right after creation.

The name rules are the same as in 4.3.2. If the project is created but the editor fails to open, an Editor open failed dialog asks whether to keep the project (Keep project) or delete it (Delete project). The QuickStart workflow itself is covered in 15. AI Assistant.

---

4.4 Project Folder Structure

PAIO creates six fixed folders on disk, but the Explorer shows only five. Each folder's purpose and display rules are as follows.

Folder	Purpose	Shown in Explorer	Files visible in the tree
doc/	Documents. Opened in the Markdown editor, HTML preview, image viewer, or text editor, depending on the extension	O	.md .markdown .html .htm .png .jpg .jpeg .gif .svg .webp .bmp .txt
design/	Model files. Shown as a model tree instead of a file list	O	See 4.5
code/	C/C++/Rust sources and build files	O	.c .cpp .h .hpp .cc .cxx .hh .hxx .rs .cmake plus CMakeLists*.txt, Makefile, Cargo.toml, Cargo.lock
workflow/	AI QuickStart workflow artifacts	O	.yaml .yml .json
export/	Export results	O	.arxml .xml .dbc
import/	Storage for import sources	X	Not shown

Items whose display and behavior differ: the import folder is really created on disk when you create a project, and it is even recovered automatically if you delete it from outside, but the entry never appears in the Explorer tree. To see what is in it, right-click the project and choose Open in File Explorer to use the OS file manager.

• PAIO writes nothing into import/. An import reads the source file you selected where it sits; it never copies the file into the project.
• PAIO does not write into workflow/ automatically either. Models produced by an AI workflow go into the design tree, and run history and presets are stored in the app's user data folder rather than in the project.

Additional display rules for the folders:

• The extension filters are for the Explorer display only. Other files in a folder are never deleted; they simply do not appear in the tree.
• Three fixed folders expand their subfolders: doc, code, and export. workflow lists files only. The target folder under code (Rust build output) is always hidden.
• In the code folder, CMakeLists.txt, Makefile, Cargo.toml, and Cargo.lock are exposed by name, independently of the extension filter, and so are .txt copies whose name starts with CMakeLists (such as CMakeLists_copy.txt).
• Fixed folders cannot be renamed or deleted. The context menu has no such entries.

---

4.5 The design Tree (Model Tree)

The design folder is shown not as files but as a semantic tree (the design tree).

design
 ├── System                 → System editor
 │    ├── IVC               → IVC editor (network topology)
 │    ├── VFB               → VFB editor (SWC structure)
 │    ├── Interface         → Interface editor
 │    ├── DataType          → DataType editor
 │    └── Signal            → Signal editor
 └── Module
      ├── Definition        (ECUC module definitions)
      └── Configuration     (ECUC module configurations)

Double-click the System node or any of the five nodes below it, or right-click and choose Open, and the matching editor opens in a tab. The tab title has the form project name:node name — for example, DoorEcu:System.

Items whose display and behavior differ: the three nodes Module, Definition, and Configuration appear in the tree but expanding them reveals no child files. The module definitions and module configurations do exist on disk. You select them in the ECUC editor's own module explorer (12. ECUC). The right-click menu on the Configuration node has the single entry Import ECUC Configuration, and the Definition and Module nodes have no right-click menu at all.

The Signal node has no right-click menu either; you open it by double-clicking. The DataType node offers import and export entries alongside Open (4.6.5).

---

Some nodes have a different tree name and tab title. The tree shows IVC, but the editor tab that opens is titled In-Vehicle Network. These are not two things; they are the same editor. The System node is also both the parent of five child nodes and a node that opens the System editor itself, so it is not a plain folder.

4.6 Working in the Explorer

4.6.1 Selecting

Use these actions to select and open items in the Explorer tree.

Action	Result
Click	Single selection
Ctrl + click	Toggles an individual item (multi-selection)
Shift + click	Selects the range from the last item you picked
Double-click	Opens the item in an editor (when the node can be opened)
Right-click	Opens the context menu. If the item you right-clicked is already in the selection, the selection is kept; otherwise it becomes the single selected item

Reopening a file that is already open does not create a new tab; it activates the existing one. At most 20 tabs can be open in total, and open requests beyond that are silently ignored.

4.6.2 Explorer Keyboard Shortcuts

These shortcuts work while the tree has focus.

Key	Action
Ctrl+C	Copies the selected files and folders
Ctrl+X	Cuts the selected files and folders
Ctrl+V	Pastes into the selected location
Ctrl+A	Selects every expanded node
Delete	Deletes the selected files and folders (shows the same confirmation dialog as right-click ▸ Delete)

Delete, cut, and copy apply only to file and folder nodes. Workspace, project, fixed folder, and model nodes are excluded, so they cannot be deleted by accident.

4.6.3 Sidebar Header Buttons

The sidebar header buttons behave as follows.

Button (tooltip)	Action
Refresh Explorer	Clears every cache and reads the disk again. Expansion state is preserved
Collapse All	Collapses everything if any node is expanded, and expands everything if none is (a toggle)
More Actions...	No action

Items whose display and behavior differ: the More Actions... button has only a tooltip and an icon; clicking it does nothing.

The second button's tooltip always reads Collapse All regardless of state, but the action alternates between collapsing and expanding as the table describes.

4.6.4 Drag and Drop

You can drag files and folders into another folder. The drop target is determined by the mouse position.

1. Hovering over the middle of a folder row means dropping into that folder. The whole folder is highlighted and the target folder name appears in the form → folder name/. Hovering about 0.6 seconds over a collapsed folder expands it automatically.
2. Hovering over the top or bottom edge of a row shows an insertion line. In this case the horizontal mouse position decides which parent folder receives the item: the further left you move, the higher the parent folder selected.
3. Releasing performs the move.

These cases are ignored: dropping an item onto itself, dropping a folder into its own subtree, and dropping an item back into the folder it already belongs to.

If the target folder already contains the same name, PAIO renames the item instead of overwriting (the name-conflict rules in 4.6.8). A failed move raises no separate error dialog.

4.6.5 Context Menus (Right-Click)

The menu differs by node type. Nodes with no menu entries show no menu at all when right-clicked.

Workspace node / empty space

Entry	Action
New Project	Creates a new project (4.3)
Refresh	Reads the project list again (on the workspace node only)

The empty-space menu appears only while a workspace is open.

Project

Entry	Action
Import	Picks an ARXML/DBC file and imports it into this project
Export	Exports this project to export/<project name>.arxml
Open in Terminal	Opens the bottom terminal panel and starts a shell in the project folder
Open in File Explorer	Opens the project folder in the OS file manager
Rename Project	Renames the project (4.7)
Delete Project	Deletes the project folder (4.7)
Paste	Pastes the item cut or copied to the clipboard (shown only while the clipboard is not empty)

The detailed import and export procedures are in 13. Import and Export.

Fixed folders

Folder	Menu
doc	New File, New Folder, and Paste when the clipboard holds something
code	New File, New Folder, and Paste when the clipboard holds something
design, workflow, export	None (no menu appears)

Ordinary folders

Entry	Notes
New File	Shown only when the path is under doc or code
New Folder	Always shown
Cut / Copy / Paste	Paste appears only when the clipboard holds something
Rename	Disabled for a multi-selection
Delete	Shown as Delete (n) for a multi-selection

Items whose display and behavior differ: clicking New Folder in a subfolder under the export folder does nothing. It works normally under doc and code.

Files

The menu entries are Open, Cut, Copy, Rename, and Delete. File nodes have no Paste. If you choose a file as the paste target, the item is pasted into the folder that contains it.

Model nodes

Node	Menu
System, IVC, VFB, Interface, DataType	Open
Signal	None
Module, Definition	None
Configuration	Import ECUC Configuration

4.6.6 Creating Files and Folders

Right-click the doc or code folder (or a subfolder of either) and choose New File.

1. The New File dialog opens. Enter a name including the extension.
2. Click Create. An empty file is created and opens immediately in an editor tab.

The allowed extensions differ by folder.

Folder	Allowed extensions	Message on violation
doc	.md, .markdown	Only Markdown files (.md) are allowed in doc folder
code	.c .h .cpp .hpp .cc .cxx .hh .hxx .rs	Only C/C++/Rust files (.c, .h, .cpp, .hpp, .cc, .cxx, .hh, .hxx, .rs) are allowed in code folder

The shared checks are as follows.

Rule	Message
Cannot be empty	File name cannot be empty
< > : " / \ | ? * are not allowed	File name contains invalid characters
An extension is required	File name must include an extension (e.g., .md) (in the code folder, (e.g., .c, .rs))
No file of the same name in the folder	"<name>" already exists in this folder

The doc folder displays images and HTML (4.4), but Markdown is the only thing you can create there. Copy images and other files in with the OS file manager and they appear in the tree.

New Folder asks only for a name (Folder name cannot be empty, Folder name contains invalid characters).

4.6.7 Renaming and Deleting

Renaming a file — right-click and choose Rename.

1. The dialog holds the name without its extension. The extension is preserved. Renaming main.c to driver, for example, produces driver.c.
2. If the target file is open with unsaved changes and its editor cannot follow the new path on its own, an Unsaved Changes confirmation appears first. Choosing Cancel cancels the rename itself. An editor that can follow the new path keeps the unsaved content without asking.
3. Once the name changes, the open tab and the edit history follow the new path.

Renaming a folder — use Rename in the same menu. If unsaved tabs exist under the folder, PAIO handles them without a confirmation dialog. An editor that can follow the new path carries its unsaved content to the new path, and an editor that cannot is saved automatically before the rename. This is because the old path disappears the moment the folder name changes, leaving nowhere to save; skipping the confirmation dialog is intended behavior.

Deleting — right-click and choose Delete, or press the Delete key. The confirmation dialog depends on the target.

Target	Dialog title	Body
One file or folder	Delete File	Are you sure you want to delete "<name>"? plus This action cannot be undone.
Several items	Delete Files	The count and up to ten names, plus This action cannot be undone.

Tabs showing a deleted file, or a file below a deleted folder, close with it. A failed deletion raises no separate error dialog.

4.6.8 Cut, Copy, and Paste

• Cut and Copy put every selected file and folder on the clipboard. The cut marker appears as dimmed text in the tree, but cutting several items at once dims only one representative item. The remaining items are still included in the paste.
• Paste pastes into the folder you selected, or into the parent folder if you selected a file.
• Pasting a folder onto itself redirects the target to the parent folder, and you cannot paste a folder into its own subtree.
• The clipboard is cleared once at least one cut-and-paste succeeds. Copy-and-paste keeps the clipboard, so you can paste repeatedly in several places.

Name-conflict rules — when a copy, move, or drag would paste onto an existing name, PAIO renames the item instead of overwriting. Pasting main.c into the same folder, for example, produces main_copy.c, and if that name is taken too, the numbers continue with main_copy2.c, main_copy3.c, and so on. Folders follow the same rule.

---

4.7 Renaming and Deleting a Project

4.7.1 Rename Project

1. Right-click the project and choose Rename Project. The dialog is prefilled with the current name.
2. Enter the new name and click Rename.

The name check differs from the one used when creating a project: the letters-and-digits restriction does not apply here. These rules do apply.

Rule	Message
Cannot be empty	Project name cannot be empty
< > : " / \ | ? * are not allowed	Project name contains invalid characters
No Windows reserved names	"<name>" is a reserved system name and cannot be used
No duplicates with another project	Project "<name>" already exists

Renaming changes the folder name and the metadata file name together, and updates the name and modification time recorded in the metadata file. Open tabs and the edit history follow the new path as well. A change of case only (test → Test) is handled in two steps through a temporary name, because of the Windows file system.

If a project operation is already in progress — deleting another project, for example — the request is ignored.

4.7.2 Delete Project

1. Right-click the project and choose Delete Project.
2. The Delete Project confirmation appears. The body reads Are you sure you want to delete "<name>"? and This action cannot be undone.
3. Click Delete. A Deleting Project progress dialog appears, every tab belonging to that project closes, and then the whole folder is deleted.

If the deletion fails, a Delete Failed dialog shows the reason.

The deleted project's edit history is removed from the Undo timeline. Otherwise a later Undo could restore deleted files to disk. The same cleanup runs when you create a project with the same name again, so the old project's content never comes back in the new project.

---

4.8 Saving

There are three save commands.

Command	Location	Action
Save	Project ▸ Save (Ctrl+S)	Saves the active editor
Save As...	Project ▸ Save As... (Ctrl+Shift+S)	See the note below
Save All	Project ▸ Save All	Saves every changed file in the active project

• A changed tab is marked with a dot (●) beside the tab title.
• Closing a changed tab brings up the Unsaved Changes confirmation. The buttons are Save, Don't Save, and Cancel.
• On app shutdown, the unsaved changes of every project are saved, not just those of the active project.
• Ctrl+S saves through the same path as the Save menu entry even when pressed outside an editor — for instance right after clicking a menu, when focus has left the editor. A Ctrl+S already handled elsewhere is not run twice.

Items whose display and behavior differ: Save As... does nothing from the menu or the global key. The actual "save as" works only when the IVC editor or the DataType editor has focus and you press Ctrl+Shift+S (see 05. UI Layout and Navigation, 5.1.2).

Saving can also be unavailable. While the license is expired or read-only, the save commands are replaced by an upgrade dialog (see 03. Installation, Login and License, 3.4).

---

4.9 Edit History (History)

The History tab in the bottom utility panel shows the project's edit timeline. This timeline is called the edit history, and the list follows the active project scope. You toggle the panel with the View ▸ Toggle Panel menu entry or with the panel button at the left of the status bar (tooltip Toggle Panel (History / Problems)). The menu also lists Ctrl+J, but that is only a label: the actual Ctrl+J key toggles the terminal panel. There is no keyboard shortcut that opens the Utility panel.

• The newest entry is at the top. Relative to the Current state marker in the middle, entries above are Redo targets (dimmed) and entries below are Undo targets. The bottom entry is Initial state.
• Each row shows an icon, a description of the action, a tag for the target editor or file, and the time (HH:MM:SS). Hovering over a row shows the full file path and the date and time in a tooltip.
• A single click selects the row; a double-click jumps to that point in one step (time travel). Double-clicking Initial state jumps to the state with every edit in this project undone.
• While a jump is in progress the list is locked and accepts no further operations.
• The list shows the history of the active project only. If there are no edits, No edits yet in this project. appears. When no project is active — for example when no tab is open — the full history is shown instead, and if it is empty, No edits yet. appears.
• History retention is managed per project. A project keeps up to 25 entries, of which bulk operations (AI generation, import, ECUC generation) keep at most 10. Whenever either limit is exceeded, the oldest entries within that project are cleaned up. One project's history never pushes out another's, and bulk operations never push out your own direct edits.
• Changing the workspace clears the entire history.

The Problems tab beside it is a placeholder that always shows only No problems have been detected. Model validation results appear in the separate VALIDATION panel (14. Validation, 05. UI Layout and Navigation).

---

4.10 Watching External Changes and Automatic Recovery

The app watches the open workspace folder.

• The watch depth is 10 levels. Files and folders whose names start with a dot (.), and node_modules, are not watched.
• After a write finishes, PAIO waits about 0.2 seconds for things to settle before handling the event, so the tree does not flicker while a large file is being copied.
• When a project is added or deleted externally, the list is read again.
• A fixed folder deleted externally is recreated automatically. All six fixed folders are covered, including import, which the Explorer does not show. Recovery is skipped, however, for a folder that is being deleted or that is no longer recognized as a project because its metadata file is gone.

When a file with an open editor changes externally, PAIO does not reload the disk content if that editor has unsaved changes. A reload would silently discard your unsaved edits. In this case the model on screen is kept, a notice that the reload was skipped appears once, and saving overwrites the disk with what is on screen. If there are no unsaved changes, the external change is applied as is.

4.11 Editing Files Directly

A project's models are stored as text JSON, so you can put them under configuration management (diff/merge) as they are. Editing them outside PAIO is not recommended, but if you must, keep the following in mind. For how the app handles external changes, see 4.10.

• Hand-editing name references that span several files can break consistency. Renaming is safer in the editor, which updates the references with it.
• The editor cannot reject a value that breaks the name rules — an empty string, whitespace, a name starting with a digit — if you enter it by hand. Names are identifiers, so references can break.
• To check for problems after editing, use the validation panel (14. Validation).