🚧 WIP

README.md

@@ -33,8 +33,8 @@ See the full interpretation matrix in the [specification](docs/SPECIFICATION.md)
 
 - Windows service (auto-start, SCM crash recovery) with a foreground `run` mode for testing
 - Local or remote (DCOM) connections to any OPC DA server
-- Server browsing: `list-servers` (discovery), `list-devices` and `list-tags`
-  (address-space walk) — live now
+- Server browsing: `list-servers` (discovery) and `list-items`
+  (address-space browse: full tree / branches / tags) — live now
 - Latency monitoring: spikes, streaks, and p95 trends against configurable thresholds
 - Hang watchdog: flags RPC calls that never return — the silent killer
 - Quality monitoring: BAD/UNCERTAIN transitions with decoded subcodes, persistent-bad
@@ -51,16 +51,15 @@ opcda-diagnozer list-servers
 opcda-diagnozer list-servers --host CONTROL-HOST01        # remote, via DCOM
 opcda-diagnozer list-servers --source registry --json     # no-COM local scan
 
-# list the devices (address-space branches) of the configured server
-opcda-diagnozer list-devices
-opcda-diagnozer list-devices --depth 2                    # include sub-devices
-opcda-diagnozer list-devices --json                       # script-friendly output
-
-# list the tags of one device (the item_id values go into config `tags:`)
-opcda-diagnozer list-tags "Simulation Items.Bucket Brigade"
-opcda-diagnozer list-tags "Simulation Items" "Bucket Brigade"   # equivalent
-opcda-diagnozer list-tags --recursive "Simulation Items"  # whole subtree
-opcda-diagnozer list-tags                                 # every tag on the server
+# browse the server's item space (list-items all|branches|tags)
+#   all      = the full structure tree: every branch AND every tag in place
+#   branches = the structure nodes (channels/devices/folders — all "branches" to OPC DA)
+#   tags     = the flat ItemID list that goes into config `tags:`
+opcda-diagnozer list-items                       # top level of the tree
+opcda-diagnozer list-items --depth 0              # the whole tree (browse.max_depth guards)
+opcda-diagnozer list-items branches --depth 2     # structure, two levels
+opcda-diagnozer list-items tags --branch "Simulation Items"   # one subtree, flat ItemIDs
+opcda-diagnozer list-items --json                 # script-friendly output
 
 # read tags right now (validation tool) — no config needed with --server
 opcda-diagnozer read --server Matrikon.OPC.Simulation.1 "Bucket Brigade.Int1"
@@ -88,15 +87,20 @@ hosts or when the wrapper DLL is not registered. `auto` tries the first, falls b
 the second. Note the bitness rule still applies: a 32-bit process enumerates the
 32-bit registry view — exactly the servers this tool can load.
 
-`list-devices` / `list-tags` browse the **connected server's** address space through
-the Automation Wrapper's browser (`CreateBrowser`): devices are *branches*, tags are
-*leaves*. They work locally and over DCOM (same Launch+Activation requirements). A
-device path is either one dotted string (`"Simulation Items.Bucket Brigade"`) or
-several quoted branch names — use the latter when a branch name itself contains a
-dot. On flat-namespace servers (`organization: flat`) every tag hangs directly off
-the root; `list-tags` without a device lists them all.
+`list-items` browses the **connected server's** address space through the
+Automation Wrapper's browser (`CreateBrowser`). OPC DA defines exactly two
+element kinds — **branches** (the structure: what SCADA vendors call channels,
+devices, groups or folders; the protocol cannot tell them apart) and **leaves**
+(the tags). The `all` view renders the full tree — including leaves that hang
+directly at the server root and belong to no branch (server-internal items
+like `@ClientCount`). It works locally and over DCOM (same Launch+Activation
+requirements). A `--branch` path is either one dotted string
+(`"Simulation Items.Bucket Brigade"`) or repeated flag segments — use the
+latter when a branch name itself contains a dot. `--depth 1` (default) lists
+one level; `--depth 0` walks the whole subtree, guarded by `browse.max_depth`
+from the config (default 32) against server-side cycles.
 
-Every connecting verb (`read`, `probe`, `list-devices`, `list-tags`) accepts
+Every connecting verb (`read`, `probe`, `list-items`) accepts
 `--server PROGID` and `--host HOST` to **override the config's `opc` section** —
 point a one-shot check at any server without touching the deployed config.yaml.
 With `--server` given, no config file is needed at all; without it, the config must
@@ -136,6 +140,9 @@ stale:
   enabled: true
   max_age_s: 120
 
+browse:
+  max_depth: 32                         # address-space walk guard (list-items --depth 0)
+
 report:
   heartbeat_s: 300
   jsonl:  { dir: "C:/ProgramData/OPCDA-Diagnozer/logs", max_mb: 50, backups: 10 }