@gotillit/tllt 0.3.0

package/diff.js

@@ -0,0 +1,158 @@
+import fs from 'fs';
+import path from 'path';
+
+import {resolveBaseDir} from './import.js';
+import {info, result} from './lib/output.js';
+
+/**
+ * Compare two imported snapshots and produce a changeset that would make the
+ * `to` snapshot match the `from` snapshot. This powers config promotion
+ * (e.g. promote stage → prod) and the deploy step.
+ *
+ *   tllt diff --from acme-stage --to acme-prod
+ *
+ * Records are matched by their snapshot-relative path, which encodes
+ * api/entity/<natural-key> — i.e. the same natural key used as the filename on
+ * import. Volatile fields (id/createdAt/updatedAt) were already stripped on
+ * import, so a content difference reflects a real configuration change.
+ */
+export function computeChangeset(fromProfile, toProfile, opts = {}) {
+  const baseDir = resolveBaseDir(opts);
+  const fromDir = snapshotDir(fromProfile, baseDir);
+  const toDir = snapshotDir(toProfile, baseDir);
+
+  const fromFiles = readSnapshot(fromDir);
+  const toFiles = readSnapshot(toDir);
+
+  const changes = [];
+  for (const [rel, from] of fromFiles) {
+    const to = toFiles.get(rel);
+    if (!to) {
+      changes.push({op: 'create', ...describe(rel, from.meta), record: from.record});
+    } else if (!deepEqual(from.record, to.record)) {
+      changes.push({op: 'update', ...describe(rel, from.meta), record: from.record, current: to.record});
+    }
+  }
+  for (const [rel, to] of toFiles) {
+    if (!fromFiles.has(rel)) {
+      changes.push({op: 'delete', ...describe(rel, to.meta), record: to.record});
+    }
+  }
+  return changes;
+}
+
+const doDiff = async (opts = {}) => {
+  const from = opts.from;
+  const to = opts.to;
+  if (!from || !to) {
+    throw new Error('diff requires --from <profile> and --to <profile>.');
+  }
+
+  const changes = computeChangeset(from, to, opts);
+  const counts = tally(changes);
+
+  info(`Diff ${from} → ${to}:  +${counts.create} create  ~${counts.update} update  -${counts.delete} delete`);
+  for (const c of changes) {
+    const glyph = c.op === 'create' ? '+' : c.op === 'delete' ? '-' : '~';
+    info(`  ${glyph} ${c.api}/${c.entity}/${c.key}`);
+  }
+
+  if (opts.out) {
+    fs.writeFileSync(opts.out, JSON.stringify({from, to, changes}, null, 2));
+    info(`\nChangeset written to ${opts.out}`);
+  }
+
+  result(`${changes.length} change(s) between ${from} and ${to}.`, {
+    ok: true,
+    from,
+    to,
+    counts,
+    changes: changes.map(({current, ...rest}) => rest),
+  });
+};
+
+export function snapshotDir(profile, baseDir) {
+  const dir = path.join(baseDir, profile);
+  if (!fs.existsSync(dir)) {
+    throw new Error(
+      `No snapshot for "${profile}" in ${baseDir}. Run \`tllt import --profile ${profile}\` first (or pass --dir).`
+    );
+  }
+  return dir;
+}
+
+/**
+ * Map of snapshot-relative path → {record, meta}, where meta is the nearest
+ * _meta.json (routing info) walking up from the record's folder. This makes
+ * entity/endpoint resolution correct even for nested layouts.
+ */
+export function readSnapshot(dir) {
+  const files = new Map();
+  walk(dir, (file) => {
+    // Skip sidecar files (_meta.json, _schema.json, _schema.source.json, ...).
+    if (path.basename(file).startsWith('_')) return;
+    if (!file.endsWith('.json')) return;
+    const rel = path.relative(dir, file).split(path.sep).join('/');
+    const meta = nearestMeta(path.dirname(file), dir);
+    files.set(rel, {record: JSON.parse(fs.readFileSync(file, 'utf8')), meta});
+  });
+  return files;
+}
+
+/** Walk up from `startDir` to `rootDir` looking for the closest _meta.json. */
+function nearestMeta(startDir, rootDir) {
+  let dir = startDir;
+  const root = path.resolve(rootDir);
+  while (true) {
+    const candidate = path.join(dir, '_meta.json');
+    if (fs.existsSync(candidate)) return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+    if (path.resolve(dir) === root) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function describe(rel, meta) {
+  const parts = rel.split('/');
+  const api = meta?.api ?? parts[0];
+  const entity = meta?.entity ?? parts[1];
+  const key = path.basename(rel, '.json');
+  return {api, entity, key, rel, meta};
+}
+
+function tally(changes) {
+  return changes.reduce(
+    (acc, c) => {
+      acc[c.op]++;
+      return acc;
+    },
+    {create: 0, update: 0, delete: 0}
+  );
+}
+
+function walk(dir, fn) {
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, fn);
+    else fn(full);
+  }
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+
+/** Stable key ordering so equality ignores property order. */
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonical(value[key]);
+    return out;
+  }
+  return value;
+}
+
+export default doDiff;

package/docs/apis.md

@@ -0,0 +1,73 @@
+# The two config surfaces
+
+The CLI manages configuration across two TilliT APIs. Both live on the same
+per-tenant connection and use the same auth (`basic` or `apikey`); you select
+entities with `--api do` / `--api scheduler`, and routing is handled for you.
+
+## DO — Digital Operations
+
+- The main configuration surface (assets, attributes, activities, …).
+- Import is **schema-driven**: the CLI learns each entity's data model from the
+  live schema and expands related records so the snapshot is self-describing.
+
+Entities snapshotted today (`./{profile}/do/...`), grouped by domain:
+
+- **Asset model**: `Asset`, `AssetClass`, `AssetProfile`, `AssetStatusColor`,
+  `AssetAttribute`, `AssetTolerance`, `AssetMeterTemplate`.
+- **Attributes & process variables**: `Attribute`, `AttributeGroup`,
+  `AttributeGroupItem`, `AttributeGroupAssignment`, `ProcessVariable`,
+  `UnitOfMeasure`, `EventType`.
+- **Sites, calendars, shifts**: `Site`, `SiteAttribute`, `ShiftTemplate`,
+  `ShiftTemplateItem`, `Calendar`, `CalendarItem`.
+- **Materials**: `MaterialGroup`, `MaterialProperty`, `Material`,
+  `MaterialAttribute`, `MaterialComponent`, `MaterialConversion`,
+  `MaterialTolerance`.
+- **Inventory movements**: `MovementType`, `MovementTypeField`.
+- **Alarms**: `AlarmType`, `AlarmTypeAssignment`.
+- **Edge & data sources**: `DatasourceTemplate`, `DatasourceTemplateTag`,
+  `DatasourceTemplateTrigger`, `DatasourceTemplateAssignment`, `Edge`,
+  `EdgeDataSource`, `EdgeDataTag`, `EdgeTrigger`.
+- **Events**: `EventRelay`, `EventSchedule`.
+- **Control parameters (recipes)**: `ControlParameter`, `ControlParameterRecipe`,
+  `ControlParameterRule`, `ControlParameterRuleAttribute`.
+- **Run rates**: `RunRateTemplate`.
+- **Order templates**: `OrderStatus`, `OrderNumberAttribute`, `OrderTemplate`,
+  `OrderTemplateComponent`, `OrderTemplateDependency`.
+- **Activities**: `ActivityClass`, `ActivityItemOptionGroup`,
+  `ActivityItemOptionItem`, `ActivityTemplate`, `ActivityTemplateItem`,
+  `ActivityStarter`, `ActivityAssignment`, `ActivityProcessStarter`,
+  `ActivityProcessTrigger`, `ActivityAssignmentAttribute`.
+
+To add an entity, extend `DO_ENTITIES` in `import.js` (entity name + optional
+filter / filename / folder nesting). Parents must appear before their children
+so deploys create them in the right order.
+
+## Scheduler
+
+- Production-scheduling configuration, driven through the **normalized REST API**
+  (`/api/scheduler/{locationCode}/{dataTemplateId}/{entity}`). **Organised per
+  `DataTemplate`** — snapshots nest under each template, and records reference one
+  another by natural key. See [`scheduler.md`](scheduler.md) before touching
+  scheduler config.
+
+Entities snapshotted today (`./{profile}/scheduler/...`):
+
+- **Global**: `Location`, `DataTemplate`, `OptimisationProfile`.
+- **Equipment**: `EquipmentClass`, `Equipment`, `EquipmentClassMembership`.
+- **Personnel**: `PersonnelClass`, `Personnel`, `PersonnelClassMembership`.
+- **Availability & downtime**: `AvailabilityTemplate`, `AvailabilityTemplateItem`,
+  `DowntimePeriod`, `EquipmentDowntimePeriod`, `PersonDowntimePeriod`.
+- **Changeovers**: `Property`, `PropertyValue`, `ChangeoverSet`,
+  `ChangeoverSetItem`.
+- **Materials**: `MaterialGroup`, `MaterialDefinition`, `MaterialProperty`.
+- **Routing**: `Operation`, `Route`, `Segment`, `SegmentMaterial`,
+  `SegmentEquipment`, `SegmentDependency`.
+
+To add an entity, extend `SCHEDULER_ENTITIES` in `lib/scheduler-entities.js`
+(descriptor: endpoint, scope, natural key, and any references).
+
+## Entity schemas
+
+Both surfaces publish a per-entity schema that the CLI fetches on import and
+exposes via `tllt schema`. See [`schemas.md`](schemas.md) for how to read
+it — it's authoritative for both APIs.

package/docs/authentication.md

@@ -0,0 +1,53 @@
+# Authentication
+
+A **connection = environment + tenant**. Each connection ("profile") records its
+own auth. Profiles live in `~/.tillit/config.json`, named `{tenant}-{environment}`.
+
+Base URL is a per-tenant subdomain derived from the environment (override with
+`--base-url`):
+
+| Environment | Base URL |
+| ----------- | -------- |
+| `prod` | `https://{tenant}.tillit.cloud` |
+| `stage` | `https://{tenant}.tillit-stage.cloud` |
+| `sandbox` | `https://{tenant}.tillit-sandbox.cloud` |
+| `dev` | `https://{tenant}.tillit-dev.cloud` |
+
+## Method 1 — basic auth
+
+```bash
+tllt configure -t acme -e prod -a basic -u alice -w 's3cret'
+```
+
+Sends `Authorization: Basic base64(<username>@<tenant>.tillit.cloud:<password>)`
+plus the `tillit-tenant: <tenant>` header.
+
+- Works against **both** the DO and Scheduler APIs.
+
+## Method 2 — api key + secret (Cognito bearer token)
+
+The api key is a Cognito app-client id; the secret is its client secret. The CLI
+performs the OAuth2 `client_credentials` flow against the tenant's Cognito token
+endpoint, then uses the returned access token as a bearer token.
+
+```bash
+tllt configure -t acme -e prod -a apikey \
+  --api-key <clientId> --api-secret <secret> \
+  --token-url https://<domain>.auth.<region>.amazoncognito.com/oauth2/token \
+  --scopes 'api/*.read,api/*.write'
+```
+
+Sends `Authorization: Bearer <token>` plus `tillit-tenant: <tenant>`.
+
+- Works against both DO and Scheduler.
+- Tokens are cached in `~/.tillit/tokens.json` until shortly before expiry.
+- `--token-url` is the Cognito hosted-domain token endpoint
+  (`.../oauth2/token`). Ask the platform team if you don't know the domain.
+
+## Files
+
+| Path | Contents |
+| ---- | -------- |
+| `~/.tillit/config.json` | profiles (mode 600) |
+| `~/.tillit/tokens.json` | cached bearer tokens (mode 600) |
+| `~/.tillit/.env` | legacy format from older CLI versions, still read |

package/docs/commands.md

@@ -0,0 +1,135 @@
+# Command reference
+
+Global options (before the command):
+
+| Flag | Meaning |
+| ---- | ------- |
+| `-p, --profile <name>` | Connection to use (default: the configured default profile) |
+| `--json` | Emit machine-readable JSON on stdout; progress on stderr (or `TILLIT_JSON=1`) |
+| `-V, --version` | Print version |
+| `-h, --help` | Help for any command |
+
+Exit codes: `0` success, non-zero on error (and on `deploy` if any change failed).
+In `--json` mode, errors are `{"ok": false, "error": "<message>"}` on stderr.
+
+---
+
+## configure (alias: init)
+
+Bootstrap or update a connection. Interactive with no flags; fully
+non-interactive when the required flags are present.
+
+| Flag | Notes |
+| ---- | ----- |
+| `-t, --tenant <tenant>` | required |
+| `-e, --environment <env>` | `prod` \| `stage` \| `sandbox` \| `dev` |
+| `-a, --auth <method>` | `basic` \| `apikey` |
+| `-u, --username` / `-w, --password` | for `basic` |
+| `--api-key` / `--api-secret` / `--token-url` | for `apikey` (Cognito) |
+| `--scopes <a,b>` | optional OAuth scopes for `apikey` |
+| `--base-url <url>` | override the derived base URL |
+| `--default` | make this the default connection |
+
+Profile is saved as `{tenant}-{environment}` in `~/.tillit/config.json`.
+
+```bash
+tllt --json configure -t acme -e prod -a basic -u alice -w 's3cret' --default
+```
+
+```json
+{ "ok": true, "profile": "acme-prod", "tenant": "acme", "environment": "prod",
+  "baseUrl": "https://acme.tillit.cloud", "authMethod": "basic", "profiles": [ ... ] }
+```
+
+## profiles (alias: connections)
+
+List configured connections. `*` marks the default.
+
+```json
+{ "ok": true, "profiles": [
+  { "name": "acme-prod", "tenant": "acme", "baseUrl": "https://acme.tillit.cloud",
+    "method": "basic", "isDefault": true } ] }
+```
+
+## schema
+
+Describe an entity's data model (fields, types, required/unique, enums, and
+relationship targets). See [`schemas.md`](schemas.md).
+
+| Arg/Flag | Notes |
+| -------- | ----- |
+| `[entity]` | entity name (e.g. `Asset`); omit to list all entities |
+| `--api <api>` | force `do` or `scheduler` (otherwise inferred) |
+| `-p, --profile <name>` | connection to fetch DO schemas from (global flag) |
+
+```bash
+tllt --json schema Asset
+```
+```json
+{ "ok": true, "schema": { "api": "do", "entity": "Asset", "naturalKey": "name",
+  "fields": [ { "name": "type", "type": "enum", "required": true,
+               "enum": ["AREA","LINE","EQUIPMENT"] } ],
+  "relationships": [ { "name": "assetClass", "kind": "many-to-one",
+                       "references": "AssetClass", "keyField": "name", "required": true } ] } }
+```
+
+## import
+
+Snapshot a connection's live configuration into `./{profile}/{api}/...` (the
+current directory, so it can live in its own git repo).
+
+| Flag | Notes |
+| ---- | ----- |
+| `-p, --profile <name>` | which connection (global flag) |
+| `--api <api>` | limit to `do` or `scheduler` |
+| `-d, --dir <path>` | output directory (default: current directory) |
+
+```json
+{ "ok": true, "profile": "acme-prod", "baseUrl": "https://acme.tillit.cloud",
+  "entities": [ { "api": "do", "entity": "Asset", "count": 26 }, ... ],
+  "skipped": [ { "api": "scheduler", "reason": "..." } ],
+  "path": "/cwd/acme-prod" }
+```
+
+A per-API failure (e.g. wrong auth method for that API) is **skipped**, not fatal.
+
+## diff
+
+Compare two snapshots and print the changeset that would make `to` match `from`.
+
+| Flag | Notes |
+| ---- | ----- |
+| `-f, --from <profile>` | required — desired state |
+| `-t, --to <profile>` | required — target |
+| `-o, --out <file>` | also write the changeset JSON to a file |
+| `-d, --dir <path>` | snapshots directory (default: current directory) |
+
+```json
+{ "ok": true, "from": "acme-stage", "to": "acme-prod",
+  "counts": { "create": 1, "update": 1, "delete": 1 },
+  "changes": [ { "op": "update", "api": "do", "entity": "Asset", "key": "Filler 1",
+                 "rel": "do/Asset/Filler 1.json", "meta": {...}, "record": {...} } ] }
+```
+
+## deploy
+
+Apply the difference between two snapshots to the live `to` target.
+
+| Flag | Notes |
+| ---- | ----- |
+| `-f, --from <profile>` | desired state (or use `--changeset`) |
+| `-t, --to <profile>` | required — the connection being changed |
+| `--changeset <file>` | apply a saved changeset instead of computing one |
+| `--api <api>` | limit to `do` or `scheduler` |
+| `--dry-run` | print the plan, change nothing (no credentials needed) |
+| `--prune` | also delete target records missing from the source (destructive) |
+| `-y, --yes` | skip the confirmation prompt (required for unattended runs) |
+| `-d, --dir <path>` | snapshots directory (default: current directory) |
+
+Without `--prune`, deletes are excluded. Without `--yes` (and not in `--json`
+mode) it prompts before applying.
+
+```json
+{ "ok": true, "to": "acme-prod", "counts": { "create": 1, "update": 1, "delete": 0 },
+  "applied": [ { "op": "create", "api": "do", "entity": "Asset", "key": "Filler 2", "ok": true } ] }
+```

package/docs/scheduler.md

@@ -0,0 +1,173 @@
+# Scheduler config — what's different
+
+Scheduler config doesn't behave quite like DO config. You never talk to the API
+directly — the CLI handles all routing — but a few things change what you see in
+snapshots and how records relate to each other.
+
+The CLI drives the Scheduler's **normalized REST API**, addressed by path:
+
+```
+/api/scheduler/{locationCode}/{dataTemplateId}/{entity}   # template-scoped
+/api/scheduler/{entity}                                   # global
+```
+
+The write shapes match the **published schema**, so unlike DO's older
+behaviour, `tllt schema <Entity>` *is* authoritative here too.
+
+## Everything is organised per DataTemplate
+
+A `DataTemplate` is the root of scheduler config (each is tied to a Location).
+Global entities (`Location`, `DataTemplate`, `OptimisationProfile`) live at the
+top of `scheduler/`; everything else belongs to exactly one template. Snapshots
+mirror that:
+
+```
+{profile}/scheduler/
+  Location/                 # global
+  DataTemplate/             # global (each carries its location)
+  OptimisationProfile/      # global
+  Line A/                   # one folder per template, keyed by NAME
+    EquipmentClass/
+    Property/  PropertyValue/
+    ChangeoverSet/  ChangeoverSetItem/
+    Equipment/  EquipmentClassMembership/
+    AvailabilityTemplate/  AvailabilityTemplateItem/
+    MaterialGroup/  MaterialDefinition/  MaterialProperty/
+    Operation/  Route/  Segment/  SegmentMaterial/  SegmentEquipment/
+```
+
+- Templates are keyed by **name**, not id (ids differ between environments).
+- On `deploy`, the CLI resolves the template name to the target's id **and**
+  location code automatically, and builds the path. If the template doesn't
+  exist on the target it is created (its `location` is resolved by code), and any
+  records scoped to it follow.
+
+## The schema is authoritative — but mind the natural keys
+
+For scheduler entities, `tllt schema <Entity>` (and the `_schema.json`
+sidecar) describes exactly what you write — fields, enums, and which entity each
+nested reference points at. Author records to that contract.
+
+Records are keyed by a **stable natural key** (the snapshot filename), so
+`diff`/`deploy` match them for update/delete — no more create-only. Some keys are
+composite (joined with ` - `):
+
+| Entity | Natural key |
+| ------ | ----------- |
+| `EquipmentClass`, `Equipment`, `MaterialGroup`, `MaterialDefinition` | `externalId` |
+| `Property`, `ChangeoverSet`, `AvailabilityTemplate`, `OptimisationProfile` | `name` |
+| `Location` | `code` |
+| `Operation` | `operationCode` |
+| `PropertyValue` | `property - value` |
+| `ChangeoverSetItem` | `set - property - fromValue - toValue` |
+| `EquipmentClassMembership` | `equipment - equipmentClass` |
+| `Route` / `Segment` | `operationCode - routeCode[ - segmentCode]` |
+
+## How references travel between environments
+
+A record's references are stored by **natural key**, never by numeric id (ids
+differ per environment). On deploy the CLI resolves them:
+
+- **Resolved by the CLI** (the create endpoint needs a numeric id): `Equipment.changeoverSet`,
+  `EquipmentClassMembership.{equipment,equipmentClass}`, `PropertyValue.property`,
+  `ChangeoverSetItem.{changeoverSet,property,fromValue,toValue}`,
+  `AvailabilityTemplateItem.availabilityTemplate`, `DataTemplate.location`,
+  `MaterialDefinition.materialGroup`, `MaterialProperty.materialDefinition`,
+  `SegmentEquipment.equipmentClass`. The CLI looks up the referenced record on the
+  target by its key and injects the id.
+- **Resolved by the API** (the body carries an inline code/externalId):
+  `Route`/`Segment`/`SegmentMaterial`/`SegmentEquipment` parents (via inline
+  `operationCode`/`routeCode`/`segmentCode`), and `SegmentMaterial.materialDefinition`
+  (`externalId`).
+
+> ⚠️ **Plain `POST /{entity}/` create endpoints do NOT resolve refs by `externalId`** —
+> only the `/upsert` routes do. So `MaterialDefinition.materialGroup`,
+> `SegmentEquipment.equipmentClass` and `MaterialProperty.materialDefinition` 500
+> (`null value in column …_id`) if sent by externalId on create; the CLI resolves
+> them to ids itself. (`SegmentMaterial.materialDefinition` is the exception — its
+> create *does* resolve by externalId.)
+
+Because of these dependencies, deploy applies creates/updates in **dependency
+order** (parents before children) and deletes in reverse. A referenced parent
+must therefore be present in the same deploy (or already on the target) — if it
+isn't, the child fails with a clear "cannot resolve …" message.
+
+## Binding changeover sets & availability to equipment (important)
+
+These two behave very differently — a hard-won learning, don't forget it:
+
+- **Changeover set → equipment: bound on create, via the `changeoverSet` ref.**
+  In the normalized model `Equipment.changeoverSet` is a **required** (`nullable:false`)
+  foreign key (`changeover_set_id`). You assign it simply by setting
+  `"changeoverSet": { "name": "<set>" }` on the equipment record — the CLI resolves
+  the name to the target id on deploy and it **persists**. There is **no separate
+  step and no "calendarised changeover" object**: the FK on the equipment row *is*
+  the assignment, and the optimiser reads it directly. Verify with
+  `GET /{loc}/{dt}/equipment?expand=changeoverSet`.
+  - ⛔️ This is the **opposite of the old flattened gateway path**, where the
+    equipment write shape had no `changeoverSet` field, so equipment was created
+    with `changeoverSet: null` and needed a separate PUT to bind. On the normalized
+    REST surface that pitfall is gone — but it also means **you cannot create
+    equipment without a changeover set** (create a `ChangeoverSet` first; deploy
+    order handles this since ChangeoverSet sorts before Equipment).
+
+  **…but binding the set is NOT enough for changeovers to apply.** The optimiser
+  computes a changeover between two segments by comparing their **property maps**,
+  and a segment's property map is built from its **SegmentMaterials →
+  MaterialDefinition → MaterialProperty** (rows where `value IS NOT NULL`) — *not*
+  from order properties and *not* from the material directly. So the full working
+  chain is:
+
+  ```
+  Equipment ──changeoverSet──▶ ChangeoverSet ──▶ ChangeoverSetItem (property, fromValue→toValue, time)
+  Segment ──▶ SegmentMaterial ──▶ MaterialDefinition ──▶ MaterialProperty (property name = value)
+  ```
+
+  For each sequenced pair the optimiser builds `{property → value}` for the from-
+  and to-segment, then looks up the matching `ChangeoverSetItem` on the line's set
+  (falling back to the set's `defaultTime`). **If a segment has no SegmentMaterial
+  carrying the relevant MaterialProperty, its property map is empty and no
+  changeover is found.** Item `fromValue`/`toValue` may be `'*'` (wildcard = any
+  value), and `aggregationType` MAX/SUM combines multiple matched properties.
+
+  > ✅ **Practical rule:** give **every** segment a SegmentMaterial carrying the
+  > keying property — not just the output stage. In two-stage canning the **fill**
+  > segment must also carry the SKU (or a recipe material with `Brand`), otherwise
+  > filling-line changeovers never compute. The pattern is to put the produced SKU
+  > on both the Fill and Pack segments.
+
+> **SegmentDependency** (`segment-dependencies`) links two segments of a route by
+> their inline codes: `{operationCode, routeCode, fromSegmentCode, toSegmentCode,
+> dependencyType, dependencyFactor}`. `dependencyType` ∈ `FINISH_START`,
+> `START_START`, `LOCKED_START_START`, `LOCKED_FINISH_START`. e.g. lock packing to
+> start with filling (no gap): `fromSegmentCode: "Fill", toSegmentCode: "Pack",
+> dependencyType: "LOCKED_START_START", dependencyFactor: "0"`.
+
+- **Availability → equipment: NOT bindable via the normalized API.** There is no
+  REST route linking an `AvailabilityTemplate` to an equipment's
+  `availabilitySetId` (a `calendarised_availability_template_set`). Availability
+  must be assigned through the **gateway** integration endpoints: `POST availabilities`
+  (one row per day: `{name, dayOfTheWeek, startTime "HH:MM:SS", endTime}`) then
+  `POST equipment-availabilities` (`{equipmentCode, availabilityCode, availabilityStart,
+  availabilityEnd}`) per line. Keep the start→end horizon to ≈1 year — the
+  `getEquipment` resolver materializes every productive period in the window, so a
+  far-future end (e.g. 2099) explodes into tens of thousands of periods and 413s
+  the schedule view.
+
+## Known API quirks the CLI works around
+
+These are pending a server-side fix; the CLI handles them so you don't have to:
+
+- **Numeric-as-string.** A few number fields are emitted as strings by the API
+  but validated as numbers on write (`ChangeoverSetItem.time`,
+  `AvailabilityTemplateItem.startTime/endTime`, `OptimisationProfile` weights).
+  The CLI stores and sends them as numbers.
+- **Unscoped leaf collections.** `property-values`, `changeover-set-items`,
+  `availability-template-items` and `material-properties` ignore the path scope
+  and return the whole tenant. The CLI filters them to the right template by the
+  parent's id (so you still see the correct per-template set).
+
+## Caveats
+
+- Always preview scheduler deploys with `--dry-run` first.
+- Transactional records (live orders) are intentionally **not** managed.

package/docs/schemas.md

@@ -0,0 +1,73 @@
+# Understanding the data model (schemas)
+
+Every record is a JSON object, but JSON alone doesn't tell you the field types,
+which fields are required, the allowed enum values, or what a nested
+`{ "name": "Site 1" }` actually points at. The CLI surfaces that contract in two
+ways.
+
+## 1. Schema sidecars in the snapshot
+
+On `import`, every entity folder gets schema sidecars next to its records:
+
+| File | What it is |
+| ---- | ---------- |
+| `_meta.json` | routing — api, microservice/endpoint, (scheduler) scope + dataTemplate |
+| `_schema.json` | **distilled, agent-friendly contract** (read this) |
+| `_schema.source.json` | the **raw authoritative schema** (the same model that drives the dynamic UI) |
+
+So an agent editing `do/Asset/Filler 1.json` can read `do/Asset/_schema.json`
+in the same folder to know exactly what's valid.
+
+### Distilled `_schema.json` shape
+
+```json
+{
+  "api": "do",
+  "entity": "Asset",
+  "endpoint": "assets",
+  "microservice": "core",
+  "naturalKey": "name",
+  "fields": [
+    { "name": "name", "type": "string", "required": true, "unique": true },
+    { "name": "type", "type": "enum", "required": true,
+      "enum": ["AREA", "LINE", "EQUIPMENT"] },
+    { "name": "displayOrder", "type": "number", "required": false }
+  ],
+  "relationships": [
+    { "name": "assetClass", "kind": "many-to-one", "references": "AssetClass",
+      "keyField": "name", "required": true },
+    { "name": "parent", "kind": "many-to-one", "references": "Asset",
+      "keyField": "name" }
+  ]
+}
+```
+
+- `naturalKey` is the field used as the filename and for cross-environment
+  matching in diff/deploy (usually `name`).
+- A relationship means the field appears in the record as
+  `{ "<keyField>": "<value>" }` (e.g. `"assetClass": { "name": "Palletisers" }`)
+  and resolves to a record of `references`.
+
+## 2. The `schema` command
+
+```bash
+tllt schema                      # list every known entity
+tllt schema Asset                # full contract for one entity (live, DO)
+tllt schema Equipment            # scheduler entity (live, under scheduler/)
+tllt --json schema Asset         # machine-readable (same shape as _schema.json)
+```
+
+## Sources & reliability
+
+Schemas are fetched **live** on import, so they're always current (the same model
+the dynamic UI uses). The fetch is best-effort: if a schema can't be retrieved,
+the import still proceeds — just without that entity's `_schema.json` sidecar.
+
+### Scheduler: the schema is authoritative too
+
+The CLI drives the Scheduler's **normalized REST API**, whose write shapes match
+the published schema — so `tllt schema <Entity>` is authoritative
+for scheduler entities just like DO. Nested references are stored by natural key
+(e.g. `"changeoverSet": { "name": "Bottling" }`) and resolved to the target's id
+on deploy. A few API quirks (number fields emitted as strings; unscoped leaf
+collections) are normalised by the CLI — see [`scheduler.md`](scheduler.md).