---
name: istari-structure
description: >
  Decide the shape of Istari Digital content — System hierarchy and Subsystems,
  folder layout, naming, and rules for a System that stays navigable. Use only when
  the person asks how to organize or structure a System, whether something should
  be a Subsystem, or before building a multi-file layout. Do not use for a simple
  upload or a first System — that is istari-models and istari-systems.
---

# istari-structure

Skip this skill unless the person asked how to **organize** or **structure** a System. A first System or a single upload is `istari-models` and `istari-systems`.

`istari-folders` is path mechanics. `istari-systems` is commit mechanics. This skill is **what to build and what to call things**. Decide it before you upload: configurations are immutable and renames are rebuilds.

## Three levels

```
PARENT SYSTEM     one per organization / trust boundary
 ├─ SUBSYSTEM     one per engineering area — a Subsystem IS a System
 │   ├─ folders
 │   └─ 00-README.html
 └─ SUBSYSTEM     …
```

The platform has no separate "subsystem" type. A parent tracks child Systems (see [Systems](/markdown-source/current/intro/key-concepts/systems.md)). Pin each child at a snapshot tag so the parent baseline is a bill-of-Systems.

Make a child its own System when it has a different audience, lifecycle, or sharing boundary — not only when it is a different discipline.

## Two layouts

| Kind                              | Layout                                                                                                                     |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Engineering / model decomposition | `01-tier-1-native/` `02-tier-2-domain-exchange/` `03-tier-3-machine-readable/` `04-tier-4-atomic-data/` `05-verification/` |
| Delivery / reporting              | `10-Analysis/` `20-Delivery/` `30-Sources/` `90-Logs/`                                                                     |

Numbered prefixes control sort order. Folder names must be ASCII (`istari-folders`).

## Naming

| Thing      | Convention                                                        |
| ---------- | ----------------------------------------------------------------- |
| Front door | `00-README.html` (`00-` sorts first; HTML renders in the web app) |
| Folders    | `NN-lowercase-hyphenated`, ASCII                                  |
| Data files | `<subject>_T<tier>_v<nnn>.<ext>` when you use tiers               |

Give every uploaded Resource a stable **external identifier** if you regenerate often. Same identifier → revise the same Resource (`istari-models`) so deep links keep working.

## Rules that keep a tree usable

1. Upload as **model** for anything a person opens from the tree.
2. Generate `00-README.html`; do not hand-edit a generated page (`istari-html-craft`).
3. Folders are `folder_path` prefixes — ASCII, helpers in `istari-folders`.
4. Deep links: `m~<resource_id>?tab=file` (`istari-links`).
5. Read link ids from the branch after commit.
6. Order: create System → upload → render README last → one commit.
7. Carry every Resource **and** its `folder_path` on rebuild (`istari-systems`).
8. Sharing is on the System (and on Resources if you grant them separately).
9. Verify branch membership of every `m~` id before sharing.