tier0-uns

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

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

read, write, and history require full topic leaf paths.
Middle folders cannot be read or written; use browse.
Topic paths must include Metric, Action, or State immediately before the leaf.
topicType is derived from that folder; do not rely on --topic-type to create the folder.
Write payload value must be an object matching the topic fields.
For batch responses, check data.success and every data.results[i].success.
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");
  }
}