mxaccesscli: document type/array support matrix from live verification

Adds a 'Type support matrix' table to docs/usage.md capturing what was
verified against the live ZB galaxy on System Platform 2017 Express
with MxAccess 3.2.0.0:

Verified read + write (round-tripped):
- MxBoolean   — DelmiaReceiver_001.TestAttribute (false→true→false)
- MxInteger   — MESReceiver_001.MoveInBatchID    (999→12345→0→999)
- MxString    — MESReceiver_001.MoveOutErrorText (round-trip + restore)
- String array element via 1-based [N] indexing
                — MESReceiver_001.MoveInPartNumbers[2] (11111→ARR-WRITE-OK→11111)

Verified read only (no writeable instance in this galaxy):
- MxFloat       — DevPlatform.CPULoad{,Avg,Max,Min}, PageFaultsAvg
- MxTime        — DevPlatform.SystemStartupTime → ISO-8601 string
- MxReferenceType — Container/Host/Area → target object's Tagname

Wired but no live instance found (matrix marked '❓'):
- MxDouble, MxElapsedTime, MxQualifiedEnum, MxInternationalizedString,
  MxBigString. Adding a writeable UDA of any of these types should
  exercise the existing code path without further changes.

Hard limitation surfaced and documented:
- MxAccess.AddItem('<obj>.<arrayAttr>') for bulk array read returns
  MxCategoryCommunicationError, Detail=1003. Read array elements
  individually via the 1-based '[N]' suffix; '[0]' is invalid.

Adds a 'Reading arrays' section pointing at grdb's attributes.sql
('array_dimension' column) for discovering element count.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mxaccesscli/docs/usage.md

@@ -113,6 +113,31 @@ LLM-JSON output (one event per line, no surrounding `[ ... ]`):
 
 JSON Lines lets a downstream consumer parse events incrementally rather than buffering the whole stream — the right shape for indefinite or long-running subscriptions.
 
+## Type support matrix
+
+Verified end-to-end against the live `ZB` galaxy (System Platform 2017 Express, MxAccess `3.2.0.0`). Each row records what the wire shape looks like in the JSON envelope.
+
+| `MxDataType` | Read | Write | JSON shape | Notes |
+| --- | :---: | :---: | --- | --- |
+| `MxBoolean`            | ✅ | ✅ | JSON `true` / `false` | `--type bool` accepts `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`. |
+| `MxInteger` (Int32)    | ✅ | ✅ | JSON number | `--type int`. Up-cast to `long` if it overflows `int.MaxValue`. |
+| `MxFloat` (single)     | ✅ | ⚠️ | JSON number | Read verified on `DevPlatform.CPULoad` family. Write requires a writeable Float UDA — none in the test galaxy, but `--type float` is wired. |
+| `MxDouble`             | ❓ | ❓ | JSON number | No accessible Double instance in the test galaxy. Wiring is identical to Float; expected to work. |
+| `MxString`             | ✅ | ✅ | JSON string | Default inferred type for non-numeric values. |
+| `MxTime` (DateTime)    | ✅ | ⚠️ | JSON string `"YYYY-MM-DDTHH:mm:ss"` | Read verified on `DevPlatform.SystemStartupTime`. Write via `--type datetime` accepts ISO-8601. |
+| `MxElapsedTime`        | ❓ | ❓ | JSON number (seconds) | No accessible instance in the test galaxy. |
+| `MxReferenceType`      | ✅ | – | JSON string (target object's `Tagname`) | E.g. `TestChildObject.Container` → `"DevTestObject"`. Writing references is not exposed by the CLI. |
+| `MxQualifiedEnum` (13) | ❓ | – | (likely string) | No accessible instance. |
+| `MxQualifiedStruct` (14) | – | – | – | Access via dotted member names: `<obj>.<struct>.<field>`. |
+| `MxInternationalizedString` (15) | ❓ | ❓ | (likely string) | No accessible instance. |
+| `MxBigString` (16)     | ❓ | ❓ | JSON string | No accessible instance. |
+| **Array (any type), bulk read** | ❌ | – | — | `MxAccess.AddItem(<arrayRef>)` → `MxCategoryCommunicationError, Detail=1003`. Bulk array reads are not supported by this LMX client API. |
+| **Array element by index** | ✅ | ✅ | scalar of element type | Reference syntax `<obj>.<arrayAttr>[<n>]`. **1-based** indexing. Verified on `MESReceiver_001.MoveInPartNumbers[2]` (String[]). `[0]` is invalid. |
+
+Legend: ✅ verified live, ⚠️ wiring present but no live instance to write, ❓ wiring present but no live instance found, ❌ not supported by MxAccess at this layer, – not applicable.
+
+To test write support for a type, use [`../../grdb/`](../../grdb/) to find a deployed instance whose `dynamic_attribute.mx_data_type` matches and whose `mx_attribute_category` is in `(2-11, 24)` ([Writeable_*](../../aot/dev-guide/appendix-f-attribute-categories.md) family).
+
 ## Errors and statuses
 
 Every `result` carries a `statuses` array — the elements of the COM `MXSTATUS_PROXY[]` MxAccess passes back. Field names match the C# struct exactly:
@@ -133,6 +158,21 @@ Common failure shapes:
 - **`Category: MxCategorySecurityError`** — secured attribute, `--user-id 0`. Use `WriteSecured` semantics (not yet exposed by this CLI) or target a `Writeable_USC_*` attribute.
 - **Timeout** — most likely the tag is genuinely silent (no value updates) or the reference is wrong. With `--llm-json` you'll see `"error": "timeout"` and an empty `statuses`.
 
+## Reading arrays
+
+MxAccess does not return array attributes as a single rowset. Bulk `AddItem("<obj>.<arrayAttr>")` returns `MxCategoryCommunicationError, Detail=1003`. Read elements individually:
+
+```powershell
+mxa read 'MESReceiver_001.MoveInPartNumbers[1]' \
+         'MESReceiver_001.MoveInPartNumbers[2]' \
+         'MESReceiver_001.MoveInPartNumbers[3]' \
+         --llm-json
+```
+
+- Array indices are **1-based** (`[1]`, `[2]`, …). `[0]` is invalid and returns a configuration error.
+- The CLI does not (yet) auto-discover the array length; combine with [`../../grdb/queries/attributes.sql`](../../grdb/queries/attributes.sql) (`array_dimension` column) to know how many elements to fetch.
+- Writing an element uses the same indexed reference: `mxa write '<obj>.<attr>[N]' <value>`.
+
 ## Picking a tag for a smoke test
 
 If the live galaxy is not familiar: