@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-rpa/references/activity-docs/UiPath.Terminal.Activities/2.10/activities.json

@@ -0,0 +1,271 @@
+{
+  "description": "Machine-readable index of UiPath.Terminal.Activities for agent / code-generation consumption. Mirrors the per-activity markdown docs under docs/activities/. Update both when adding or changing an activity.",
+  "package": "UiPath.Terminal.Activities",
+  "namespaceUri": "http://schemas.uipath.com/workflow/activities/terminal",
+  "xamlPrefix": "uit",
+  "activities": [
+    {
+      "xamlElement": "TerminalSession",
+      "className": "UiPath.Terminal.Activities.TerminalSession",
+      "displayName": "Terminal Session",
+      "category": "App Integration.Terminals",
+      "requiredScope": null,
+      "requiredProperties": [],
+      "optionalProperties": ["ConnectionString", "ExistingConnection", "OutputConnection", "CloseConnection", "SSHUserName", "SSHPassword", "TimeoutMS", "DelayMS", "ContinueOnError"],
+      "outputProperties": ["OutputConnection"],
+      "isContainer": true,
+      "docPath": "activities/TerminalSession.md"
+    },
+    {
+      "xamlElement": "TerminalGetText",
+      "className": "UiPath.Terminal.Activities.TerminalGetText",
+      "displayName": "Get Text",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": [],
+      "optionalProperties": ["Text", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Text"],
+      "isContainer": false,
+      "docPath": "activities/GetText.md"
+    },
+    {
+      "xamlElement": "TerminalGetField",
+      "className": "UiPath.Terminal.Activities.TerminalGetField",
+      "displayName": "Get Field",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": [],
+      "optionalProperties": ["LabeledBy", "FollowedBy", "Index", "Text", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Text"],
+      "isContainer": false,
+      "docPath": "activities/GetField.md",
+      "notes": "At least one of LabeledBy or FollowedBy must be set. Label-based field identification varies by provider — for cross-provider workflows prefer GetTextAtPosition or GetScreenArea."
+    },
+    {
+      "xamlElement": "TerminalSetField",
+      "className": "UiPath.Terminal.Activities.TerminalSetField",
+      "displayName": "Set Field",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Text"],
+      "optionalProperties": ["LabeledBy", "FollowedBy", "Index", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/SetField.md",
+      "notes": "At least one of LabeledBy or FollowedBy must be set. Label-based field identification varies by provider — for cross-provider workflows prefer MoveCursor+SendKeys or SetFieldAtPosition."
+    },
+    {
+      "xamlElement": "TerminalGetCursorPosition",
+      "className": "UiPath.Terminal.Activities.TerminalGetCursorPosition",
+      "displayName": "Get Cursor Position",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": [],
+      "optionalProperties": ["Row", "Column", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Row", "Column"],
+      "isContainer": false,
+      "docPath": "activities/GetCursorPosition.md"
+    },
+    {
+      "xamlElement": "TerminalSendControlKey",
+      "className": "UiPath.Terminal.Activities.TerminalSendControlKey",
+      "displayName": "Send Control Key",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Key"],
+      "optionalProperties": ["TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/SendControlKey.md",
+      "notes": "Key is an enum (ControlKey). Common values: Transmit (3270 enter), Return (VT enter), Tab, F1-F24."
+    },
+    {
+      "xamlElement": "TerminalWaitScreenText",
+      "className": "UiPath.Terminal.Activities.TerminalWaitScreenText",
+      "displayName": "Wait Screen Text",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Text"],
+      "optionalProperties": ["MatchCase", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/WaitScreenText.md",
+      "defaults": { "TimeoutMS": 30000 }
+    },
+    {
+      "xamlElement": "TerminalWaitFieldText",
+      "className": "UiPath.Terminal.Activities.TerminalWaitFieldText",
+      "displayName": "Wait Field Text",
+      "category": "App Integration.Terminals",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Text"],
+      "optionalProperties": ["LabeledBy", "FollowedBy", "Index", "MatchCase", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/WaitFieldText.md",
+      "defaults": { "TimeoutMS": 30000 },
+      "notes": "At least one of LabeledBy or FollowedBy must be set."
+    },
+    {
+      "xamlElement": "TerminalMoveCursor",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalMoveCursor",
+      "displayName": "Move Cursor",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column"],
+      "optionalProperties": ["TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/MoveCursor.md"
+    },
+    {
+      "xamlElement": "TerminalSendKeys",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalSendKeys",
+      "displayName": "Send Keys",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Keys"],
+      "optionalProperties": ["TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/SendKeys.md",
+      "notes": "Plaintext only. Use SendKeysSecure for credentials."
+    },
+    {
+      "xamlElement": "TerminalSendKeysSecure",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalSendKeysSecure",
+      "displayName": "Send Keys Secure",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["SecureText"],
+      "optionalProperties": ["TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/SendKeysSecure.md"
+    },
+    {
+      "xamlElement": "TerminalWaitScreenReady",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalWaitScreenReady",
+      "displayName": "Wait Screen Ready",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": [],
+      "optionalProperties": ["TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/WaitScreenReady.md",
+      "defaults": { "TimeoutMS": 30000, "DelayMS": 0 },
+      "notes": "Always waits for READY regardless of WaitType. Avoid placing as the very first child after a fresh TLS connect — see TerminalSession DelayMS tuning."
+    },
+    {
+      "xamlElement": "TerminalGetScreenArea",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalGetScreenArea",
+      "displayName": "Get Screen Area",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column", "EndRow", "EndColumn"],
+      "optionalProperties": ["Text", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Text"],
+      "isContainer": false,
+      "docPath": "activities/GetScreenArea.md"
+    },
+    {
+      "xamlElement": "TerminalGetTextAtPosition",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalGetTextAtPosition",
+      "displayName": "Get Text at Position",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column"],
+      "optionalProperties": ["Length", "Text", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Text"],
+      "isContainer": false,
+      "docPath": "activities/GetTextAtPosition.md"
+    },
+    {
+      "xamlElement": "TerminalGetFieldAtPosition",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalGetFieldAtPosition",
+      "displayName": "Get Field at Position",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column"],
+      "optionalProperties": ["Text", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Text"],
+      "isContainer": false,
+      "docPath": "activities/GetFieldAtPosition.md"
+    },
+    {
+      "xamlElement": "TerminalGetColorAtPosition",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalGetColorAtPosition",
+      "displayName": "Get Color at Position",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column"],
+      "optionalProperties": ["TerminalColor", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["TerminalColor"],
+      "isContainer": false,
+      "docPath": "activities/GetColorAtPosition.md",
+      "notes": "Color support depends on the provider. TandemHLL always returns LightGreen."
+    },
+    {
+      "xamlElement": "TerminalSetFieldAtPosition",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalSetFieldAtPosition",
+      "displayName": "Set Field at Position",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column", "Text"],
+      "optionalProperties": ["BackwardsCompatible", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/SetFieldAtPosition.md",
+      "notes": "Set BackwardsCompatible=false for new workflows to get cursor-stays-at-end behavior."
+    },
+    {
+      "xamlElement": "TerminalWaitTextAtPosition",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalWaitTextAtPosition",
+      "displayName": "Wait Text at Position",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Row", "Column", "Text"],
+      "optionalProperties": ["MatchCase", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": [],
+      "isContainer": false,
+      "docPath": "activities/WaitTextAtPosition.md",
+      "defaults": { "TimeoutMS": 30000 }
+    },
+    {
+      "xamlElement": "TerminalFindTextInScreen",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalFindTextInScreen",
+      "displayName": "Find Text",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Text"],
+      "optionalProperties": ["StartRow", "StartColumn", "IgnoreCase", "Row", "Column", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Row", "Column"],
+      "isContainer": false,
+      "docPath": "activities/FindText.md",
+      "notes": "Throws InvalidCoordinates if not found."
+    },
+    {
+      "xamlElement": "TerminalMoveCursorToText",
+      "className": "UiPath.Terminal.Advanced.Activities.TerminalMoveCursorToText",
+      "displayName": "Move Cursor to Text",
+      "category": "App Integration.Terminals.Advanced",
+      "requiredScope": "TerminalSession",
+      "requiredProperties": ["Text"],
+      "optionalProperties": ["StartRow", "StartColumn", "IgnoreCase", "Row", "Column", "TimeoutMS", "DelayMS", "WaitType"],
+      "outputProperties": ["Row", "Column"],
+      "isContainer": false,
+      "docPath": "activities/MoveCursorToText.md",
+      "notes": "Throws InvalidCoordinates if not found. Equivalent to FindText + MoveCursor."
+    }
+  ],
+  "commonOptions": {
+    "docPath": "activities/TerminalSession/_common-options.md",
+    "appliesTo": "all entries with requiredScope == 'TerminalSession'",
+    "properties": {
+      "TimeoutMS": { "type": "InArgument<int>", "typicalDefault": 5000, "waitActivityDefault": 30000 },
+      "DelayMS":   { "type": "InArgument<int>", "typicalDefault": 300,  "waitScreenReadyDefault": 0 },
+      "WaitType":  { "type": "WaitMode property", "default": "READY", "enum": ["NONE", "READY", "COMPLETE"] }
+    }
+  }
+}

package/skills/uipath-rpa/references/activity-docs/UiPath.Terminal.Activities/2.10/coded/coded-api.md

@@ -31,18 +31,69 @@ In coded workflow mode, all `TerminalConnection` methods **throw `TerminalConnec
 
 ---
 
+## Coded Quickstart
+
+The smallest working coded workflow — open a session, send a command, read the screen. Six required fields on `ConnectionData` (plus `TerminalModel` when the default model for the chosen `TerminalType` is not what you want); every other property takes its type default.
+
+```csharp
+[Workflow]
+public string Execute()
+{
+    var connData = new ConnectionData
+    {
+        Host = "telehack.com",
+        Port = 23,
+        ProviderType = TerminalProviderType.UiPathNew,
+        ConnectionType = ConnectionType.Address,
+        ConnectionProtocol = CommunicationType.TELNET,
+        TerminalType = TerminalType.TerminalVT,
+        TerminalModel = (int)TTVtTermId.VT100,
+    };
+
+    using var conn = terminal.GetConnection(connData);
+    conn.WaitText("Connected to TELEHACK");
+    conn.SendKeys("date");
+    conn.SendControlKey(ControlKey.Return);
+    conn.WaitScreenReady();
+    conn.GetText(out var screen);
+    return screen;
+}
+```
+
+> **Do not carry the JSON connection-string field set into this object literal.** The "all `ConnectionData` properties must be present" rule documented under [TerminalSession.md § Connection String Format](../activities/TerminalSession.md#connection-string-format) is enforced by the JSON validator only. With `GetConnection(ConnectionData)`, unset fields take their type defaults — populating `Ehll*`, proxy fields, `InternalEncoding`, or `ShowTerminal` when you are not using EHLLAPI, a proxy, a non-default encoding, or hiding the window is noise.
+
+For protocol-, provider-, or terminal-type variations (3270 over Telnet, TN5250 over TLS, SSH with credentials, EHLLAPI, Tandem/NonStop), see [Common Patterns](#common-patterns) below.
+
+---
+
 ## Connection Methods
 
 ### `TerminalConnection GetConnection(string connectionString)`
 
-Opens a terminal connection using a serialized connection string. The connection string encodes the provider type, host, port, protocol, and other settings. Use the **Terminal Session** XAML activity's Connection Settings dialog to generate a valid string.
+Opens a terminal connection using a serialized connection string — a JSON-serialized `ConnectionData` object with the same format the **Terminal Session** XAML activity's `ConnectionString` property accepts.
+
+> **Prefer `GetConnection(ConnectionData)` from coded workflows.** That overload takes a strongly-typed object — no string-format pitfalls. Use this string overload only when the connection string is supplied externally (e.g. read from configuration, or copied from a Studio-generated Terminal Session activity).
 
 **Parameters:**
-- `connectionString` (`string`) — Serialized connection string. Example: obtained by configuring a Terminal Session activity and copying the `ConnectionString` property value.
+- `connectionString` (`string`) — JSON-serialized `ConnectionData`. The format has serializer quirks: single quotes around property names and string values, integer enum values (not string names), all `ConnectionData` properties present. See [TerminalSession.md § Connection String Format](../activities/TerminalSession.md#connection-string-format) for the full rules.
+
+**Example string** (UiPathNew provider, plain Telnet, port 23, no SSL):
+```
+{'AttachExisting':false,'ConnectionProtocol':0,'ConnectionType':1,'EhllBasicMode':false,'EhllDll':null,'EhllEnhanced':true,'EhllFunction':'hllapi','EhllSession':'A','EnableSSL':false,'Host':'myhost.com','InProcessMode':false,'InternalEncoding':'ASCII','Mode':1,'Port':23,'Profile':null,'ProviderType':9,'ProxyHost':null,'ProxyPassword':null,'ProxyPort':0,'ProxyType':0,'ProxyUser':null,'ShowTerminal':true,'TerminalModel':3,'TerminalType':2}
+```
+
+**Example string — TN5250 over TLS** (UiPathNew provider, IBM i / AS/400 host `pub400.com`, TLS on port 992):
+```
+{'AttachExisting':false,'ConnectionProtocol':0,'ConnectionType':1,'EhllBasicMode':false,'EhllDll':null,'EhllEnhanced':true,'EhllFunction':'hllapi','EhllSession':'A','EnableSSL':true,'Host':'pub400.com','InProcessMode':false,'InternalEncoding':'ASCII','Mode':1,'Port':992,'Profile':null,'ProviderType':9,'ProxyHost':null,'ProxyPassword':null,'ProxyPort':0,'ProxyType':0,'ProxyUser':null,'ShowTerminal':true,'TerminalModel':0,'TerminalType':1}
+```
+
+The integer enum values are NOT in the order listed under [Enum Reference](#enum-reference) below — those lists are by display order, not numeric value. Copy a string generated by Studio's **Connection Settings** dialog and substitute scenario-specific fields rather than hand-deriving the integers.
 
 **Returns:** `TerminalConnection` — An open, connected terminal session. Implements `IDisposable`; use inside a `using` statement.
 
-**Throws:** `TerminalConnectionException` if the connection cannot be established within the timeout.
+**Throws:** `TerminalConnectionException` if the connection cannot be established within the timeout, or if `connectionString` is not a valid serialized `ConnectionData`.
+
+> **Note:** `GetConnection` returns as soon as the transport-level connection is established. The terminal session negotiation (e.g. TN5250/TN3270 data stream setup, initial screen delivery) continues asynchronously after that. Follow the call with a `WaitText` for a string expected on the initial screen to ensure it has loaded before interacting with it. A fixed-delay alternative (1–2 s) also works but is less robust.
 
 ---
 
@@ -57,6 +108,8 @@ Opens a terminal connection using a `ConnectionData` object, allowing programmat
 
 **Throws:** `TerminalConnectionException` if the connection cannot be established.
 
+> **Note:** `GetConnection` returns as soon as the transport-level connection is established. The terminal session negotiation (e.g. TN5250/TN3270 data stream setup, initial screen delivery) continues asynchronously after that. Follow the call with a `WaitText` for a string expected on the initial screen to ensure it has loaded before interacting with it. A fixed-delay alternative (1–2 s) also works but is less robust.
+
 ---
 
 ### `TerminalConnection GetSshConnection(ConnectionData connectionData, string sshUser, SecureString sshPassword)`
@@ -349,6 +402,7 @@ Programmatic configuration object for terminal connections. Used with `GetConnec
 | `ProviderType` | `TerminalProviderType` | `UiPathNew` | Terminal emulator provider. Use `UiPathNew` for direct TCP/SSH connections. |
 | `ConnectionType` | `ConnectionType` | `Profile` | How the connection is established: `Address` (host/port — required for `UiPathNew`), `Profile` (provider profile file), `LowLevel` (EHLLAPI). |
 | `ConnectionProtocol` | `CommunicationType` | `TELNET` | Protocol: `TELNET`, `SSH`, or `HPVT`. |
+| `Mode` | `ConnectionMode` | `Play` | Operating mode for the connection. `Play` (the default) opens a normal session for workflow-driven interaction. `Record` is reserved for the Studio Terminal Recorder wizard and should not be used in workflow code. Must be present in serialized connection strings (`'Mode':1`); the validator rejects connection strings that omit it. |
 | `TerminalType` | `TerminalType` | `Terminal3270` | Terminal emulation type. |
 | `Host` | `string` | | Hostname or IP address of the target host. |
 | `Port` | `int` | `23` | TCP port. Default is 23 (Telnet); SSH typically uses 22. |
@@ -410,6 +464,10 @@ Represents a row/column location on the terminal screen.
 
 **`CommunicationType`**: `TELNET`, `SSH`, `HPVT`
 
+**`ConnectionMode`**: `Record`, `Play`
+- `Play` — Normal operating mode. Use this in workflow code.
+- `Record` — Reserved for the Studio Terminal Recorder wizard. Do not use in workflow code; the connection lifecycle differs from `Play`.
+
 **`ConnectionType`**: `Address`, `Profile`, `LowLevel`
 - `Address` — Connect by host/port. Required when using `ProviderType.UiPathNew`.
 - `Profile` — Connect using a provider-specific profile file (path set via `Profile`).

package/skills/uipath-rpa/references/activity-docs/UiPath.Terminal.Activities/2.10/overview.md

@@ -8,6 +8,82 @@ Terminal emulation activities for automating interactions with IBM 3270/5250, VT
 
 - [XAML Activities Reference](activities/) — Per-activity documentation for XAML workflows
 - [Coded Workflow API Reference](coded/coded-api.md) — Service API for coded C# workflows
+- [Machine-readable activity index](activities.json) — JSON listing of every activity's class name, required properties, output properties, and doc path. For code generators and agents that need the activity surface without parsing markdown.
+
+## If you want to ...
+
+Quick task → activity lookup. Each row points at the activity that does the thing with the fewest assumptions.
+
+| Task | Use |
+|------|-----|
+| Open a session and run a few activities | [`TerminalSession`](activities/TerminalSession.md) (start here) |
+| **Synchronize before any read or write** | [`WaitScreenText`](activities/WaitScreenText.md) (most reliable), [`WaitScreenReady`](activities/WaitScreenReady.md) (after a control key), [`WaitTextAtPosition`](activities/WaitTextAtPosition.md), or [`WaitFieldText`](activities/WaitFieldText.md). Reading without a preceding wait returns stale data on real hosts. |
+| Type a literal string into the terminal | [`SendKeys`](activities/SendKeys.md) |
+| Type a password without logging it | [`SendKeysSecure`](activities/SendKeysSecure.md) |
+| Press Enter, Tab, F-keys, or any control key | [`SendControlKey`](activities/SendControlKey.md) (use `Transmit` for 3270 enter, `Return` for VT enter) |
+| Wait for the keyboard to unlock after sending a key | [`WaitScreenReady`](activities/WaitScreenReady.md) |
+| Wait for specific text to appear anywhere | [`WaitScreenText`](activities/WaitScreenText.md) |
+| Wait for specific text at known coordinates | [`WaitTextAtPosition`](activities/WaitTextAtPosition.md) |
+| Wait for a named input field to contain text | [`WaitFieldText`](activities/WaitFieldText.md) |
+| Read the entire visible screen | [`GetText`](activities/GetText.md) |
+| Read a rectangular region | [`GetScreenArea`](activities/GetScreenArea.md) |
+| **Extract tabular data into a `DataTable`** | [`GetScreenArea`](activities/GetScreenArea.md) → `Generate Data Table` (from `UiPath.System.Activities`). See [GetScreenArea.md § Extracting tabular data as a DataTable](activities/GetScreenArea.md#extracting-tabular-data-as-a-datatable) |
+| Read N characters starting at a row/col | [`GetTextAtPosition`](activities/GetTextAtPosition.md) (cross-provider safe) |
+| Read the field at a row/col (provider-agnostic) | [`GetFieldAtPosition`](activities/GetFieldAtPosition.md) |
+| Read a labeled input field (single-provider) | [`GetField`](activities/GetField.md) — see the [provider portability caveat](activities/GetField.md#prefer-position-based-reads-when-portability-matters); prefer position-based reads above if the workflow must run against multiple providers |
+| Write to the field at a row/col (provider-agnostic) | [`SetFieldAtPosition`](activities/SetFieldAtPosition.md) |
+| Write to a labeled input field (single-provider) | [`SetField`](activities/SetField.md) — see the [provider portability caveat](activities/SetField.md#prefer-position-based-writes-when-portability-matters); prefer [`MoveCursor`](activities/MoveCursor.md) + [`SendKeys`](activities/SendKeys.md) or `SetFieldAtPosition` for cross-provider work |
+| Find where a string appears on screen | [`FindText`](activities/FindText.md) (returns Row/Column) |
+| Move the cursor to coordinates | [`MoveCursor`](activities/MoveCursor.md) |
+| Find a string and move the cursor there | [`MoveCursorToText`](activities/MoveCursorToText.md) |
+| Read the current cursor location | [`GetCursorPosition`](activities/GetCursorPosition.md) |
+| Detect a highlighted / error-colored character | [`GetColorAtPosition`](activities/GetColorAtPosition.md) |
+| **Close a session you kept open via `OutputConnection`** | A second [`TerminalSession`](activities/TerminalSession.md#closing-a-saved-connection) with empty body and `CloseConnection="True"` |
+
+## XAML Setup
+
+All terminal activity XAML snippets in this documentation use the `uit:` prefix. The required namespace declaration on the root `<Activity>` element is:
+
+```
+xmlns:uit="http://schemas.uipath.com/workflow/activities/terminal"
+```
+
+Do **not** infer this URL from the package name — `clr-namespace:UiPath.Terminal.Activities;assembly=UiPath.Terminal.Activities` is plausible but incorrect; using it causes silent activity-resolution failures (`validate` passes, `build` fails with unknown element / member errors).
+
+## Known Authoring Pitfalls
+
+These trip both XAML and coded authors regularly. Read once before authoring; they do not surface as friendly error messages.
+
+### `validate` clean ≠ buildable
+
+`uip rpa validate` (and Studio's lightweight Validate button) checks XAML structure, references, expression syntax, and analyzer rules. It does **not** execute the WF activity-constraint runner for this package. Constraints — including the parent-scope check that ensures every child activity sits inside a `TerminalSession` — only run at **pack / build** time (`uip rpa build`, Studio's Pack/Publish). Consequences:
+
+- A file that passes `validate` can still fail `build` with a constraint error.
+- Iterating on `validate` alone is not sufficient verification. After every edit, also run `uip rpa build` (or pack from Studio) and treat that as the truthful check.
+- A `validate` run can inherit the cached state of a prior `build`. If a previous `build` populated `.local/install/`, a subsequent `validate` may *also* surface the constraint runner's verdict — i.e. validate is not always stateless. If you see `validate` flip from clean to red after a build attempt, that is why.
+
+### `String.Format(format, arg1, arg2, …)` in WF expressions can crash the interpreter
+
+On newer .NET SDK toolchains (.NET 8+ Roslyn / BCL), the C# / VB compiler resolves `String.Format` calls with multiple arguments to overloads whose argument set involves `ReadOnlySpan<string>` (introduced in .NET 8). The WF expression *interpreter*, used by the activity-constraint runner at pack time, then tries to construct `Func<…, ReadOnlySpan<string>>` and fails with `TypeLoadException` — `ReadOnlySpan<T>` is a `ref struct` and cannot be a generic type argument. The full stack ends in `System.RuntimeType.MakeGenericType`.
+
+Symptom (during `uip rpa build` or Studio Pack):
+
+```
+Internal constraint exception while running constraint with name 'Constraint<TerminalActivity<String>>'
+  System.ArgumentException: GenericArguments[1], 'System.ReadOnlySpan`1[System.String]',
+  on 'System.Linq.Expressions.Interpreter.FuncCallInstruction`2[T0,TRet]'
+  violates the constraint of type 'TRet'.
+  ---> System.TypeLoadException: …
+```
+
+Mitigations, any one of them:
+
+- **Use `&` (VB) or `+` (C#) concatenation** to compose the string. Overload resolution stays on `String.Concat(string, string, …)`, no span overload involved.
+- **For `ConnectionString` specifically, avoid string composition altogether** — build a typed `ConnectionData` and serialize it (see [authoring-paths.md § Option B](activities/TerminalSession/authoring-paths.md#option-b--xaml-build-a-connectiondata-and-serialize-with-connectionstringhelperserialize)).
+- **Force the legacy `String.Format` overload** by passing an explicit `object[]`: `String.Format(format, New Object() { arg1, arg2, arg3 })`. The compiler binds to `String.Format(String, params Object[])` rather than the span family.
+- **Pre-format outside the expression**: assemble the string in a coded helper or a sequence of `&` concatenations, then pass the result into the activity argument.
+
+Note: this is not specific to Terminal Activities — any package whose constraints use the WF expression interpreter is affected. It surfaces here because most child activities in this package carry a parent-scope constraint that runs at pack time.
 
 ## Activities