Systems and Snapshots

A System is the primary organizing concept in Istari. Systems contain Configurations (sets of tracked files) and Snapshots (point-in-time captures of those configurations).

Browse Systems

1. Click Systems in the sidebar (or navigate to /systems).
2. You will see a grid of system cards showing each system's name, description, creator, and creation date.
3. Use the global Search in the left sidebar (or press ⌘ K / Ctrl K) to find systems by name, description, creator, or configuration.
4. Systems are loaded in pages of 50. If more are available, a Load more button appears at the bottom of the grid (up to 100 systems are fetched from the API).

Each system card displays:

• The system name (clickable — opens the system)
• A configuration badge showing the latest configuration name (click to navigate directly to that configuration)
• If the system has multiple configurations, a popover appears listing all configurations
• The creator's name and avatar
• The creation date
• An optional infosec badge if information security levels are enabled

Create a System

1. Navigate to the Systems page.
2. Click the Create button (with plus icon) in the top-right corner.
3. In the dialog that appears:
   • Enter a Name for the system (defaults to "Untitled system").
   • Optionally add a Description.
4. Click Create.
5. You will be automatically redirected to the new system's detail page.

View System Details

1. From the Systems page, click on a system card to open it.
2. The system detail page has two main panels:
   • Left panel (Explorer): Shows the version menu (configurations and snapshots) and the snapshot file tree.
   • Right panel (Content): Shows the selected file's preview, metadata, and activity.
3. Breadcrumbs at the top show: Systems > System Name. Hover over the system name to see its description.

Edit a System

1. Open the system you want to edit.
2. Click the ⋯ (more options) menu in the top-right corner of the page.
3. Select Edit system details.
4. Update the Name and/or Description in the dialog.
5. Click Save.

Required role: Editor, Administrator, or Owner.

Archive a System

1. Open the system you want to archive.
2. Click the ⋯ menu in the top-right corner.
3. Select Archive system.
4. Confirm the action in the dialog that appears.

You can also archive a system directly from the Systems grid page by clicking the ⋯ menu on the system card and selecting Archive.

Required role: Owner only.

Configurations

A Configuration defines which files are tracked within a system.

Create a Configuration

1. Open a system.
2. In the left panel (Explorer), click the + (Layers Plus) icon at the top of the version menu.
3. In the Create Configuration dialog, select the files to track.
4. Click Create.

Required role: Editor or above.

Archive / Restore a Configuration

1. In the left panel, expand the version menu to see all configurations.
2. Hover over a configuration name and click the ⋯ menu.
3. Select Archive configuration (or Restore if it is already archived).
4. To see archived configurations, check the Show archived checkbox in the version menu.

Mark a Configuration as Baseline

1. In the version menu, hover over a non-baseline configuration.
2. Click the ⋯ menu.
3. Select Mark as baseline.

The configuration must have at least one snapshot.

Snapshots

A Snapshot captures the current state of a configuration's tracked files at a point in time.

Capture a Snapshot

1. Open a system that has file changes pending.
2. In the left panel, a "New Snapshot Available" banner appears.
3. Click Capture Changes to create a new snapshot.

Required role: Editor or above.

Browse Snapshots

1. In the left panel, expand a configuration in the version menu.
2. All snapshots are listed under their parent configuration, showing creation dates and creator avatars.
3. Click a snapshot to load its file tree in the explorer below.

Add Tags to a Snapshot

1. Expand a configuration in the version menu.
2. Next to a snapshot, click the tag area to add or edit tags inline.

Compare Snapshots (Diff)

1. Open a system.
2. Click the ⋯ menu in the top-right corner.
3. Select Compare versions.
4. In the Compare Snapshots modal:
   • Select a left snapshot and a right snapshot using the snapshot selectors.
   • The diff viewer displays changes between the two snapshots (added, removed, and modified files).

Upload Files to a System

Drag and Drop

1. Open the system detail page.
2. Drag files from your computer and drop them anywhere on the page.
3. The Upload Spec dialog appears — fill in metadata (display name, tags, infosec level, etc.).
4. After upload completes, you may be prompted to create a new configuration or add the files to an existing one.

Using the File Tree

1. In the left panel file tree, look for the Upload option.
2. Click it to open a file picker dialog and select files from your computer.

Required role: Editor or above.

Browse the Snapshot File Tree

1. Open a system and select a snapshot from the version menu.
2. The left panel shows a file tree with:
   • Files organized in a hierarchical folder structure.
   • Artifact groups nested under their parent files (grouped by the job that produced them).
   • Job group nodes showing the tool/function name that produced the artifacts (click the job name to view job details).
3. Click any file to view its preview, metadata, and actions in the right panel.

Branching

Experimental feature

Enable Branching in Application settings → Experimental Features. See Settings.

When branching is enabled, system navigation is branch-first: each system has a tree of branches instead of only configurations and snapshots.

1. Open a system. The left panel shows a Branches section with the branch tree (hierarchical names separated by /).
2. Select a branch to load its HEAD commit and file tree.
3. Create a branch from the current HEAD or from a historical commit (Create Branch dialog) — Editor or above.
4. Archive or restore branches from the branch tree. The default baseline branch cannot be archived until another branch is promoted to baseline.
5. Promote a branch into the baseline (merge) when the source branch is at its latest commit — Editor or above.
6. View commit history for a branch in the branch history section.

When branching is off, systems use the configuration and snapshot model described above.

System Composition

Experimental feature

Enable System Composition in Application settings → Experimental Features. See Settings.

When enabled, you can track other systems inside a configuration alongside files. Linked systems appear as subsystems in the snapshot file tree and can nest when those systems track their own subsystems.

The Systems sidebar icon switches from the default link icon to a network icon.

View subsystems in the file tree

1. Open a system and select a configuration and snapshot (or branch HEAD when branching is enabled).
2. In the left Explorer file tree, subsystem rows appear above tracked files (network icon and system name).
3. Expand a subsystem to browse its tracked files and any nested subsystems.
4. Click a subsystem to open its Subsystem summary in the right panel (system ID, classification, link metadata, and which configuration snapshot is tracked).
5. Click a file under a subsystem to preview it in the right panel.

Use the subsystem context menu (right-click) to Open subsystem, copy link or title, Set version source (baseline or a configuration tag), Edit system details, Share, or Untrack subsystem.

Required role: Editor or above to add, change, or remove tracked systems in a configuration.

Add or edit tracked systems in a configuration

1. Open a system and start Create Configuration (empty system) or click Edit files (layers-plus control in the version bar) for the active configuration.
2. The configuration builder splits the explorer:
   • Top: current tracked subsystems and files for the configuration.
   • Bottom: SYSTEMS and FILES library panels.
3. Under SYSTEMS, search or browse available systems and click one to add it, or use Create system to add a new system inline.
4. For each tracked system, choose the version source — baseline or a specific configuration tag — from the dropdown next to the system name.
5. Under FILES, add or remove tracked files as usual.
6. Enter a configuration name (when creating) and click Save.

You cannot add the current system or a system already tracked in the configuration. Remove a draft subsystem with the × control or Untrack subsystem in the context menu.

If you open a shared link to a subsystem while the toggle is off, the platform enables System Composition automatically and shows a notice pointing you to Application settings.

System Documents

Experimental feature

Enable System Documents in Application settings → Experimental Features. See Settings.

When enabled:

1. A Documents section appears in the snapshot file tree.
2. Click a document to open it in the Document Editor in the right panel.
3. Toggle between View mode and Edit mode using the ?mode=edit URL parameter or the edit toggle in the UI.
4. Documents support export functionality.

Edit permissions are controlled per-document based on individual document access grants.

Workflow Log

Experimental feature

Enable Workflow Log in Application settings → Experimental Features. See Settings.

The Workflow log tab records runs of work performed outside Istari — scripts, CI jobs, batch runs — whose outputs are uploaded back to the system. Each entry links its output files to the configuration that was active when the run took place. Workflow outputs are kept separate from tracked files and do not appear in snapshots.

Browse and view entries

1. Open a system and select the Workflow log tab.
2. Entries are listed with title, status, configuration, and file count, most recent first.
3. Click an entry to view its detail and preview or download the output files.

Create an entry

Workflow log entries are created from your external workflow via the SDK. See External workflow logs.

Archive / Restore an entry

1. In the Workflow log tab, hover over an entry and click the ⋯ menu.
2. Select Archive entry (or Restore if it is already archived).

Required role: Editor or above.

Download Snapshot Files

1. Open a system and select a snapshot.
2. In the top action bar, click the Download button.
3. A Download selected files panel appears. Select the files you want from the snapshot tree.
4. Click Download to download the selected files.