---
name: istari-systems
description: >
  Istari Digital Systems and branches on SDK 13.x — create a System, commit revisions
  with branch.commit, create branches and change requests; drop to the Client
  configuration recipe when the tree has folders. Use for "create/update a system",
  "add this file to the system", "commit to the branch", or "baseline".
metadata:
  sdk: istari-digital-client
  sdk-major: "13"
  sdk-range: ">=13.0,<14"
  skill-version: "13.0.1"
  verified-sdk: "13.0.1"
  verified-registry: "demo 11.1.0"
  verified-on: "2026-09-08"
---

# istari-systems

Concepts: [Systems](/markdown-source/current/intro/key-concepts/systems.md), [Version control](/markdown-source/current/intro/key-concepts/version-control.md).

```
System → Branches (a branch is a snapshot tag; one has is_baseline=True)
Branch → Snapshot → Configuration = immutable list of tracked Resources
TrackedResource from branch.files() = Resource + specifier Latest|Locked + path
```

A branch shows **committed** state, not the latest uploads. `LATEST` resolves when the snapshot is taken. Revising a Resource in place does not disturb a released branch — do not duplicate a Resource "to protect baseline".

## Commit without folders

```python
s = client.systems.create(name="…", description="…")  # description is required
base = s.get_branch("baseline")
rev = client.resources.revisions.list(RID).items[0]  # newest first
base = base.commit(add=[rev])  # pins rev as LOCKED
base.files().total
```

`add` takes objects with `.id` = a **file-revision id**. Carried-forward files keep their specifier. `commit` returns the updated `Branch`.

**Remove** needs `.id` equal to `current_file_revision_id`. `TrackedResource` has no `.id` — wrap it:

```python
class Rev:
    def __init__(self, i):
        self.id = i
tr = next(f for f in base.files() if f.name == "old.stl")
base = base.commit(remove=[Rev(tr.current_file_revision_id)])
```

## Folders

`branch.commit()` rebuilds the configuration **without** `folder_path`. On a System whose tree has folders, one facade commit puts every Resource at the root.

**If any tracked path has folders, do not use `commit()`.** Use the `Client` recipe in `istari-folders` (carry every `folder_path` forward). Record the prior `snapshot_id` before `update_tag`.

## Branches and change requests

```python
review = s.create_branch("review", from_branch=base)
review = review.commit(add=[rev2])  # baseline untouched — only if the tree is flat
cr = review.create_change_request(base, title="…", description="…")
cr.change_request_id, cr.status  # "OPEN"
merged = cr.merge(comment="…")   # "MERGED"
```

Folders on a non-baseline branch use the same `Client` recipe, picking the tag named `"review"` (or whatever you created). Carry **every** existing tracked Resource forward when you add one, or the branch silently drops them.

| Signal                         | Meaning                                                               |
| ------------------------------ | --------------------------------------------------------------------- |
| Tree flat after a commit       | facade `commit()` on a foldered System — rebuild via `istari-folders` |
| `duplicate tracked files`      | `add` of a revision already tracked at that pin                       |
| `description Field required`   | `systems.create` needs a description; pass `""` if you have none      |
| UI unchanged after API success | on the `Client` path you skipped `update_tag`                         |