tier0-uns

name	tier0-uns
description	Tier0 UNS operations: browse, read, write, history, search, create, update, delete, and restore namespace nodes and topics.

tier0-uns

Use this skill for Tier0 Unified Namespace data-plane and namespace-management tasks.

Use When

• The user asks to browse namespace paths or discover topics.
• The user asks to read current topic values.
• The user asks to write values into UNS topics.
• The user asks for historical values or aggregates.
• The user asks to create, update, delete, or restore namespace nodes.

Do Not Use When

• The user wants to manage Node-RED SourceFlow/EventFlow containers. Use flow/SKILL.md.
• The user wants API key diagnostics. Use auth/whoami.md.
• The user wants service connectivity only. Use info/info.md.

Non-Negotiable Rules

1. read, write, and history require full topic leaf paths.
2. Middle folders cannot be read or written; use browse.
3. Topic paths must include Metric, Action, or State immediately before the leaf.
4. topicType is derived from that folder; do not rely on --topic-type to create the folder.
5. Write payload value must be an object matching the topic fields.
6. For batch responses, check data.success and every data.results[i].success.
7. Use --path for delete. --topic is a deprecated alias only for compatibility.

Routing

Intent	Read
Browse namespace folders	references/browse.md
Read current values	references/read.md
Write current values	references/write.md
Query history or aggregates	references/history.md
Search topics by keyword or path prefix	references/search.md
Create nodes or import a tree	references/create.md
Update metadata or fields	references/update.md
Delete nodes	references/delete.md
Restore soft-deleted nodes	references/restore.md

Topic Path Rules

Valid examples:

Plant/Line1/Metric/Temperature
Plant/Line1/State/MachineStatus
Machine/Action/Start

Invalid:

Plant/Line1/Temperature

The invalid path is missing the type folder before the leaf.

Common Commands

tier0 uns browse --path /
tier0 uns search --keyword Temperature --json
tier0 uns read Plant/Line1/Metric/Temperature --json
tier0 uns write --topic Plant/Line1/Metric/Temperature --value '{"temperature":27.5}'
tier0 uns history -t Plant/Line1/Metric/Temperature --start -1h --json
tier0 uns create --topic Plant/Line1/Metric/Temperature --type topic --fields '[{"name":"temperature","type":"float"}]'
tier0 uns delete --path Plant/Line1/Metric/Temperature --hard --yes

Batch Response Handling

UNS batch APIs can return HTTP 200 while one or more business items fail.

Required checks:

if (resp.data?.success === false) {
  throw new Error("UNS batch operation failed");
}
for (const result of resp.data?.results ?? []) {
  if (result.success === false) {
    throw new Error(result.message || result.topic || result.path || "UNS item failed");
  }
}