@uipath/skills 1.195.0

package/skills/uipath-agents/references/lowcode/capabilities/process/solution-files.md

@@ -0,0 +1,548 @@
+# Solution-Level Files for External Process Tools — Hand-Authoring Reference
+
+When `uip solution resource refresh` cannot produce solution-level files (offline, missing RCS match, custom deployment), hand-author them using the templates below. For the standard auto-generated path, see [process.md](process.md).
+
+It also documents the Releases API + `GetPackageEntryPointsV2` + JWT decoding extraction path — used when `uip solution resource get` is unavailable (older `uip` builds, RCS unreachable, custom deployments). For the standard CLI-driven extraction, see [process.md § Discovery](process.md#discovery).
+
+> **`folders[].fullyQualifiedName` carries the literal `Folder`** (e.g., `"Shared"`, `"Shared/Sales"`) returned by `uip solution resource list` — the same value the agent-level `resource.json` writes into `properties.folderPath` and that `bindings_v2.json` propagates. Templates show `<Folder>` as the placeholder; examples show `"Shared"` as a concrete value. Auto-generated declarations for **solution-internal projects** (created when the agent project is registered with the solution — by `uip agent init` auto-registration or by the `uip solution project add` fallback) keep `"solution_folder"` instead — they have no fixed Orchestrator folder until deploy. See [../../critical-rules.md](../../critical-rules.md) Rule 11.
+
+## Directory Structure
+
+```
+<SolutionName>/
+├── <SolutionName>.uipx
+├── <AgentName>/
+│   ├── agent.json
+│   └── resources/
+│       └── <ToolName>/
+│           └── resource.json            # Agent-level resource (see process.md)
+├── resources/
+│   └── solution_folder/
+│       ├── package/
+│       │   ├── <AgentName>.json         # Agent package (auto-generated when project is registered with solution)
+│       │   └── <PackageName>.json       # External tool package declaration (YOU CREATE THIS)
+│       └── process/
+│           ├── agent/
+│           │   └── <AgentName>.json     # Agent process (auto-generated when project is registered with solution)
+│           ├── process/                 # ← RPA processes (type: "process")
+│           ├── api/                     # ← API workflows (type: "api")
+│           └── processOrchestration/    # ← Agentic processes (type: "processOrchestration")
+│               └── <ToolName>.json      # External tool process declaration (YOU CREATE THIS)
+└── userProfile/
+    └── <userId>/
+        └── debug_overwrites.json        # Folder resolution for Studio Web (YOU CREATE THIS)
+```
+
+The process declaration directory depends on the tool type. Place the file in the subdirectory matching the `ProcessType` from the Releases API: `process/` for RPA, `agent/` for agents, `api/` for API workflows, `processOrchestration/` for agentic processes.
+
+## Process Declaration
+
+**Path:** `resources/solution_folder/process/<type_dir>/<ToolName>.json`
+
+Declares the external process as a solution resource. The structure differs between RPA processes and all other types (Agent, API, Agentic Process). Get the values from the Releases API and `GetPackageEntryPointsV2` (see § How to Get the Values below).
+
+| ProcessType | `resource.type` | `spec.type` | Directory | Schema approach |
+|---|---|---|---|---|
+| `Process` (RPA) | `process` | `Process` | `process/process/` | `inputArgumentsSchema`/`outputArgumentsSchema` (raw .NET arrays) |
+| `Agent` | `agent` | `Agent` | `process/agent/` | `inputArgumentsSchemaV2`/`outputArgumentsSchemaV2` (JSON Schema) |
+| `Api` | `api` | `Api` | `process/api/` | `inputArgumentsSchemaV2`/`outputArgumentsSchemaV2` (JSON Schema) |
+| `ProcessOrchestration` | `processOrchestration` | `ProcessOrchestration` | `process/processOrchestration/` | `inputArgumentsSchemaV2`/`outputArgumentsSchemaV2` (JSON Schema) |
+
+**Key differences:**
+- **RPA**: Uses `inputArgumentsSchema`/`outputArgumentsSchema` (raw .NET type arrays from `Arguments.Input`/`Arguments.Output`). V2 schema fields and entry point fields are `null`. Has extra spec fields: `jobPriority`, `jobRecording`, `duration`, `frequency`, `quality`, `remoteControlAccess`.
+- **Agent/API/Agentic**: Uses `inputArgumentsSchemaV2`/`outputArgumentsSchemaV2` (JSON Schema from `GetPackageEntryPointsV2`). Populates `entryPointUniqueId`, `entryPointName`, `entryPoints`. Old-style schema fields are `null`. Agent type adds `agentMemory`, `targetRuntime`, `environmentVariables`, `referencedAssets`.
+
+### Template A — RPA Process (`type: "process"`)
+
+**Path:** `resources/solution_folder/process/process/<ToolName>.json`
+
+Uses `inputArgumentsSchema`/`outputArgumentsSchema` (raw .NET type arrays from `Arguments.Input`/`Arguments.Output`). Entry point fields and V2 schema fields are `null`.
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "<ToolName>",
+    "kind": "process",
+    "type": "process",
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [
+      {
+        "name": "<PackageName>",
+        "kind": "Package"
+      }
+    ],
+    "runtimeDependencies": [],
+    "files": [],
+    "folders": [
+      { "fullyQualifiedName": "<Folder>" }
+    ],
+    "spec": {
+      "type": "Process",
+      "jobPriority": "Medium",
+      "jobRecording": "Disabled",
+      "duration": 40,
+      "frequency": 500,
+      "quality": 100,
+      "remoteControlAccess": "None",
+      "name": "<ToolName>",
+      "package": {
+        "name": "<PackageName>",
+        "key": "<PackageName>:<Version>"
+      },
+      "packageName": "<PackageName>",
+      "packageVersion": "<Version>",
+      "entryPointUniqueId": null,
+      "entryPointName": null,
+      "inputArguments": null,
+      "inputArgumentsSchema": "<raw Arguments.Input string from Releases API>",
+      "outputArgumentsSchema": "<raw Arguments.Output string from Releases API>",
+      "inputArgumentsSchemaV2": null,
+      "outputArgumentsSchemaV2": null,
+      "hiddenForAttendedUser": false,
+      "alwaysRunning": false,
+      "autoStartProcess": false,
+      "targetFrameworkValue": "Portable",
+      "retentionAction": "Delete",
+      "retentionPeriod": 30,
+      "retentionBucketRef": null,
+      "staleRetentionAction": "Delete",
+      "staleRetentionPeriod": 180,
+      "staleRetentionBucketRef": null,
+      "entryPoints": null,
+      "connections": null,
+      "tags": [],
+      "description": null
+    },
+    "locks": [],
+    "key": "<release-key-guid>"
+  }
+}
+```
+
+#### Example: RPA Process
+
+**Path:** `resources/solution_folder/process/process/TestRPA.json`
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "TestRPA",
+    "kind": "process",
+    "type": "process",
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [
+      {
+        "name": "TestRPA.process.TestRPA",
+        "kind": "Package"
+      }
+    ],
+    "runtimeDependencies": [],
+    "files": [],
+    "folders": [
+      { "fullyQualifiedName": "Shared" }
+    ],
+    "spec": {
+      "type": "Process",
+      "jobPriority": "Medium",
+      "jobRecording": "Disabled",
+      "duration": 40,
+      "frequency": 500,
+      "quality": 100,
+      "remoteControlAccess": "None",
+      "name": "TestRPA",
+      "package": {
+        "name": "TestRPA.process.TestRPA",
+        "key": "TestRPA.process.TestRPA:1.0.0"
+      },
+      "packageName": "TestRPA.process.TestRPA",
+      "packageVersion": "1.0.0",
+      "entryPointUniqueId": null,
+      "entryPointName": null,
+      "inputArguments": null,
+      "inputArgumentsSchema": "[\n  {\n    \"name\": \"name\",\n    \"type\": \"System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e\",\n    \"required\": false,\n    \"hasDefault\": true\n  }\n]",
+      "outputArgumentsSchema": "[\n  {\n    \"name\": \"greeting\",\n    \"type\": \"System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e\"\n  }\n]",
+      "inputArgumentsSchemaV2": null,
+      "outputArgumentsSchemaV2": null,
+      "hiddenForAttendedUser": false,
+      "alwaysRunning": false,
+      "autoStartProcess": false,
+      "targetFrameworkValue": "Portable",
+      "retentionAction": "Delete",
+      "retentionPeriod": 30,
+      "retentionBucketRef": null,
+      "staleRetentionAction": "Delete",
+      "staleRetentionPeriod": 180,
+      "staleRetentionBucketRef": null,
+      "entryPoints": null,
+      "connections": null,
+      "tags": [],
+      "description": null
+    },
+    "locks": [],
+    "key": "cc69568b-e686-4737-bf62-7ed6ddb0849b"
+  }
+}
+```
+
+### Template B — Agent / API Workflow / Agentic Process
+
+**Path:** `resources/solution_folder/process/<type_dir>/<ToolName>.json` where `<type_dir>` is `agent/`, `api/`, or `processOrchestration/`.
+
+Uses `inputArgumentsSchemaV2`/`outputArgumentsSchemaV2` (JSON Schema strings from `GetPackageEntryPointsV2`). Populates `entryPointUniqueId`, `entryPointName`, and `entryPoints`. Old-style schema fields are `null`. No RPA-specific spec fields (`jobPriority`, `jobRecording`, etc.).
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "<ToolName>",
+    "kind": "process",
+    "type": "<type>",                       // "agent", "api", or "processOrchestration"
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [
+      {
+        "name": "<PackageName>",
+        "kind": "Package"
+      }
+    ],
+    "runtimeDependencies": [],
+    "files": [],
+    "folders": [
+      { "fullyQualifiedName": "<Folder>" }
+    ],
+    "spec": {
+      "type": "<Type>",                     // "Agent", "Api", or "ProcessOrchestration" (PascalCase)
+      // Agent-only fields (include ONLY when type = "agent"):
+      // "agentMemory": false,
+      // "targetRuntime": "pythonAgent",
+      // "environmentVariables": "",
+      // "referencedAssets": null,
+      "name": "<ToolName>",
+      "package": {
+        "name": "<PackageName>",
+        "key": "<PackageName>:<Version>"
+      },
+      "packageName": "<PackageName>",
+      "packageVersion": "<Version>",
+      "entryPointUniqueId": "<UniqueId from GetPackageEntryPointsV2>",
+      "entryPointName": "<Path from GetPackageEntryPointsV2>",
+      "inputArguments": null,
+      "inputArgumentsSchema": null,
+      "outputArgumentsSchema": null,
+      "inputArgumentsSchemaV2": "<InputArguments JSON Schema string from GetPackageEntryPointsV2>",
+      "outputArgumentsSchemaV2": "<OutputArguments JSON Schema string from GetPackageEntryPointsV2>",
+      "hiddenForAttendedUser": false,
+      "alwaysRunning": false,
+      "autoStartProcess": false,
+      "targetFrameworkValue": "Portable",
+      "retentionAction": "Delete",
+      "retentionPeriod": 30,
+      "retentionBucketRef": null,
+      "staleRetentionAction": "Delete",
+      "staleRetentionPeriod": 180,
+      "staleRetentionBucketRef": null,
+      "entryPoints": "<serialized JSON array — see below>",
+      "connections": null,
+      "tags": [],
+      "description": null
+    },
+    "locks": [],
+    "key": "<release-key-guid>"
+  }
+}
+```
+
+**`entryPoints` serialized JSON format** (for Agent/API/Agentic Process only):
+
+Construct a JSON array, then serialize it as a string. Use data from `GetPackageEntryPointsV2`:
+
+```jsonc
+[{
+  "UniqueId": "<UniqueId>",
+  "Path": "<Path>",
+  "DisplayName": null,
+  "InputArguments": "<InputArguments string>",   // Same as inputArgumentsSchemaV2
+  "OutputArguments": "<OutputArguments string>", // Same as outputArgumentsSchemaV2
+  "Type": <numeric_type>,                       // 1=Process, 2=ProcessOrchestration, 4=Agent, 6=Api
+  "TargetRuntime": null,
+  "ContentRoot": null,
+  "DataVariation": null,
+  "Id": <Id>
+}]
+```
+
+#### Example: Agent
+
+**Path:** `resources/solution_folder/process/agent/TestAgent.json`
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "TestAgent",
+    "kind": "process",
+    "type": "agent",
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [
+      {
+        "name": "TestAgentSolution.agent.TestAgent",
+        "kind": "Package"
+      }
+    ],
+    "runtimeDependencies": [],
+    "files": [],
+    "folders": [
+      { "fullyQualifiedName": "Shared" }
+    ],
+    "spec": {
+      "type": "Agent",
+      "agentMemory": false,
+      "targetRuntime": "pythonAgent",
+      "environmentVariables": "",
+      "referencedAssets": null,
+      "name": "TestAgent",
+      "package": {
+        "name": "TestAgentSolution.agent.TestAgent",
+        "key": "TestAgentSolution.agent.TestAgent:1.0.0"
+      },
+      "packageName": "TestAgentSolution.agent.TestAgent",
+      "packageVersion": "1.0.0",
+      "entryPointUniqueId": "02ff7040-604a-481f-8336-235de71e2b4b",
+      "entryPointName": "content/agent.json",
+      "inputArguments": null,
+      "inputArgumentsSchema": null,
+      "outputArgumentsSchema": null,
+      "inputArgumentsSchemaV2": "{\n  \"type\": \"object\",\n  \"properties\": {}\n}",
+      "outputArgumentsSchemaV2": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"content\": {\n      \"type\": \"string\",\n      \"description\": \"Output content\"\n    }\n  }\n}",
+      "hiddenForAttendedUser": false,
+      "alwaysRunning": false,
+      "autoStartProcess": false,
+      "targetFrameworkValue": "Portable",
+      "retentionAction": "Delete",
+      "retentionPeriod": 30,
+      "retentionBucketRef": null,
+      "staleRetentionAction": "Delete",
+      "staleRetentionPeriod": 180,
+      "staleRetentionBucketRef": null,
+      "entryPoints": "[{\"UniqueId\":\"02ff7040-604a-481f-8336-235de71e2b4b\",\"Path\":\"content/agent.json\",\"DisplayName\":null,\"InputArguments\":\"{\\n  \\\"type\\\": \\\"object\\\",\\n  \\\"properties\\\": {}\\n}\",\"OutputArguments\":\"{\\n  \\\"type\\\": \\\"object\\\",\\n  \\\"properties\\\": {\\n    \\\"content\\\": {\\n      \\\"type\\\": \\\"string\\\",\\n      \\\"description\\\": \\\"Output content\\\"\\n    }\\n  }\\n}\",\"Type\":4,\"TargetRuntime\":null,\"ContentRoot\":null,\"DataVariation\":null,\"Id\":790954}]",
+      "connections": null,
+      "tags": [],
+      "description": null
+    },
+    "locks": [],
+    "key": "f6084607-a81c-45f1-90e4-ffe8fed22c53"
+  }
+}
+```
+
+## Package Declaration
+
+**Path:** `resources/solution_folder/package/<PackageName>.json`
+
+Declares the package for the external process. The `<PackageName>` is the `ProcessKey` from the `/odata/Releases` response — e.g., `MyProcess.process.MyProcess`. Format is **identical for all 4 process types** — only the package name and version change.
+
+**Important:** If the package is in a solution-specific feed (its `FeedId` from the Releases API differs from the tenant feed), append `?feedId=<FEED_ID>` to the download URL. This applies to **all** process types (agents, API workflows, agentic processes, RPA), not just agents. Without this, Studio Web reports "Resource '...' is missing in this environment."
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "<PackageName>",
+    "kind": "package",
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [],
+    "runtimeDependencies": [],
+    "files": [
+      {
+        "name": "<PackageName>.<Version>.nupkg",
+        "kind": "Package",
+        "version": "<Version>",
+        "url": "<orchBase>/odata/Processes/UiPath.Server.Configuration.OData.DownloadPackage(key='<URL_ENCODED_PACKAGE_KEY>')",
+        "key": "<PackageName>_<Version_underscores>"   // Dots replaced with underscores: "MyProcess.process.MyProcess_1_0_0"
+      }
+    ],
+    "folders": [
+      {
+        "fullyQualifiedName": "<Folder>"
+      }
+    ],
+    "spec": {
+      "fileName": "<PackageName>.<Version>.nupkg",
+      "fileReference": "<PackageName>_<Version_underscores>",  // Same as files[0].key
+      "name": "<PackageName>",
+      "description": null
+    },
+    "locks": [],
+    "key": "<PackageName>:<Version>"       // e.g., "MyProcess.process.MyProcess:1.0.0" (colon separator)
+  }
+}
+```
+
+**URL construction:**
+- `<orchBase>` = `${UIPATH_URL}/${UIPATH_ORGANIZATION_NAME}/${UIPATH_TENANT_NAME}/orchestrator_`
+- `<URL_ENCODED_PACKAGE_KEY>` = URL-encode `<PackageName>:<Version>` (e.g., `MyProcess.process.MyProcess%3A1.0.0`)
+- `<Version_underscores>` = version with dots replaced by underscores (e.g., `1.0.0` → `1_0_0`)
+- **Solution-feed packages:** If the external tool was deployed from a solution (its `FeedId` from the Releases API differs from the tenant-level feed), append `?feedId=<FEED_ID>` to the download URL. This applies to **all** process types (agents, API workflows, agentic processes, RPA), not just agents. Without this, Studio Web reports "Resource '...' is missing in this environment."
+
+### Example: Package Declaration
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "name": "TestRPA.process.TestRPA",
+    "kind": "package",
+    "apiVersion": "orchestrator.uipath.com/v1",
+    "isOverridable": true,
+    "dependencies": [],
+    "runtimeDependencies": [],
+    "files": [
+      {
+        "name": "TestRPA.process.TestRPA.1.0.0.nupkg",
+        "kind": "Package",
+        "version": "1.0.0",
+        "url": "<orchestrator-download-url>",
+        "key": "TestRPA.process.TestRPA_1_0_0"
+      }
+    ],
+    "folders": [
+      { "fullyQualifiedName": "Shared" }
+    ],
+    "spec": {
+      "fileName": "TestRPA.process.TestRPA.1.0.0.nupkg",
+      "fileReference": "TestRPA.process.TestRPA_1_0_0",
+      "name": "TestRPA.process.TestRPA",
+      "description": null
+    },
+    "locks": [],
+    "key": "TestRPA.process.TestRPA:1.0.0"
+  }
+}
+```
+
+## debug_overwrites.json (process kind)
+
+**Path:** `userProfile/<userId>/debug_overwrites.json`
+
+Maps `solution_folder` to the actual Orchestrator folder so Studio Web can resolve external tool references during import and debugging. **Required for external tools** — without this file, Studio Web will show "resource is missing in this environment".
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "tenants": [
+    {
+      "tenantKey": "<UIPATH_TENANT_ID>",   // From ~/.uipath/.auth
+      "resources": [
+        {
+          "solutionResourceKey": "<release-key-guid>",  // Same as referenceKey in agent resource
+          "reprovisioningIndex": 0,
+          "overwrite": {
+            "resourceKey": "<release-key-guid>",
+            "resourceName": "<ToolName>",
+            "folderKey": "<folder-key-guid>",            // FolderKey from `uip solution resource list --kind Process`
+            "folderFullyQualifiedName": "<folder-path>", // Folder from the same (e.g., "Shared/MyFolder")
+            "folderPath": "<parent-key>.<folder-key>",   // If folder has parent: "parentKey.folderKey". If no parent: just "folderKey"
+            "type": "Reference",
+            "kind": "process"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Multiple external tools:** Add one entry per tool to the `resources` array. If a resource with the same `solutionResourceKey` already exists, replace it.
+
+For the generic debug_overwrites shape (capability-agnostic), see [../../solution-resources.md](../../solution-resources.md) § Debug Overwrites.
+
+## How to Get the Values
+
+> **Fallback path.** When `uip solution resource get` is available, use it instead — see [process.md § Discovery](process.md#discovery). The steps below are for older `uip` builds, RCS-unreachable environments, or custom deployments where the CLI cannot supply the full configuration.
+
+> **SECURITY: Never read `~/.uipath/.auth` directly** — the access token must not appear in Claude's context. Always use a `bash -c` wrapper that sources the auth file and makes the API call in a single shell invocation, so Claude only sees the API response.
+
+### Step 1: Discover the process and its folder
+
+```bash
+uip solution resource list --kind Process --source remote --search "<NAME>" --output json
+```
+
+Returns, for each match:
+- `Key` — release Key GUID. Use as `referenceKey` in the agent resource and `key` in the process declaration.
+- `Type` — maps 1:1 to the agent resource `type` and the process declaration directory:
+  - `process` → `process/process/`
+  - `agent` → `process/agent/`
+  - `api` → `process/api/`
+  - `processOrchestration` → `process/processOrchestration/`
+- `Folder` — literal Orchestrator folder path (e.g., `"Shared/Sales"`). Use as: agent-level `resource.json` `properties.folderPath`, solution-level `folders[].fullyQualifiedName` (in both process and package declarations), and `folderFullyQualifiedName` in `debug_overwrites.json`.
+- `FolderKey` — folder GUID. Use as `X-UIPATH-FolderKey` header in Steps 2-3 and as `folderKey` in `debug_overwrites.json`.
+
+### Step 2: Query `/odata/Releases` for ProcessKey, ProcessVersion, FeedId, and raw .NET schemas (RPA)
+
+Use a shell wrapper to query the Releases API — this keeps the access token inside the shell. Filter by `ProcessKey` (string, exact match):
+
+```bash
+bash -c 'A="$HOME/.uipath/.auth"; [ -f "$A" ] || A="/.uipath/.auth"; set -a; source "$A"; set +a; curl -s "${UIPATH_URL}/${UIPATH_ORGANIZATION_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/Releases?\$filter=ProcessKey%20eq%20'\''<PROCESS_KEY>'\''&\$top=1&\$select=Key,Name,ProcessKey,ProcessVersion,ProcessType,FeedId,TargetRuntime,Description,Arguments,Id" \
+  -H "Authorization: Bearer $UIPATH_ACCESS_TOKEN" \
+  -H "X-UIPATH-FolderKey: <FOLDER_KEY_GUID>"'
+```
+
+Orchestrator's OData rejects `Key eq <guid>` (Edm.Guid mismatch); filter by `ProcessKey` (string) or `Name` instead. The `Key` GUID from Step 1 is used as `referenceKey` and process-declaration `key`, never as a filter value.
+
+Returns:
+- `ProcessKey` / `ProcessVersion` → build `"<ProcessKey>:<Version>"` package key for Step 3
+- `FeedId` → package feed ID, required by `GetPackageEntryPointsV2` in Step 3
+- `TargetRuntime` → `"pythonAgent"` for agents, `null` for others — used in agent process declarations
+- `Arguments.Input` / `Arguments.Output` → raw .NET type array strings (only populated for RPA processes, `null` for others) — used as `inputArgumentsSchema` / `outputArgumentsSchema` in RPA process declarations
+
+### Step 3: Query `GetPackageEntryPointsV2` for schemas and entry point data
+
+This API returns JSON Schema format input/output arguments and entry point metadata. It works for **all 4 process types**.
+
+```bash
+bash -c 'A="$HOME/.uipath/.auth"; [ -f "$A" ] || A="/.uipath/.auth"; set -a; source "$A"; set +a; curl -s "${UIPATH_URL}/${UIPATH_ORGANIZATION_NAME}/${UIPATH_TENANT_NAME}/orchestrator_/odata/Processes/UiPath.Server.Configuration.OData.GetPackageEntryPointsV2(key='\''<PROCESS_KEY>:<VERSION>'\'')?feedId=<FEED_ID>" \
+  -H "Authorization: Bearer $UIPATH_ACCESS_TOKEN" \
+  -H "X-UIPATH-FolderKey: <FOLDER_KEY_GUID>"'
+```
+
+- `<PROCESS_KEY>:<VERSION>` — e.g., `TestRPA.process.TestRPA:1.0.0` (from Step 2: `ProcessKey` + `ProcessVersion`)
+- `feedId` — from Step 2 `FeedId`. Always pass it; required for agents published via solution feeds.
+
+Returns (array — take the first entry):
+- `UniqueId` → `entryPointUniqueId` in process declaration (non-RPA types)
+- `Path` → `entryPointName` in process declaration (non-RPA types)
+- `InputArguments` → JSON Schema string — use for agent-level `inputSchema` (parse the JSON) and `inputArgumentsSchemaV2` in process declaration (non-RPA types)
+- `OutputArguments` → JSON Schema string — use for agent-level `outputSchema` (parse the JSON) and `outputArgumentsSchemaV2` in process declaration (non-RPA types)
+- `Type` → numeric entry point type (1=Process, 2=ProcessOrchestration, 4=Agent, 6=Api) — used in `entryPoints` serialized array
+- `Id` → entry point ID — used in `entryPoints` serialized array
+
+### Step 4: Build agent-level inputSchema/outputSchema
+
+Parse the `InputArguments`/`OutputArguments` JSON Schema strings from Step 3 and use them directly as the `inputSchema`/`outputSchema` in the agent-level `resource.json`. This works for all 4 types.
+
+**Fallback for RPA only:** If `GetPackageEntryPointsV2` is unavailable, parse `Arguments.Input`/`Arguments.Output` from Step 2 using this .NET type mapping:
+
+| .NET Type | JSON Schema Type |
+|-----------|-----------------|
+| `System.String` | `"string"` |
+| `System.Int32`, `System.Int64`, `System.Decimal`, `System.Double` | `"number"` |
+| `System.Boolean` | `"boolean"` |
+| Unknown | `"string"` (default) |
+
+Extract the short type name: split by `,` → take first part → split by `.` → take last part. Example: `"System.String, System.Private.CoreLib, ..."` → `"String"` → `"string"`.
+
+### Step 5: Extract userId from JWT
+
+Decode the JWT access token payload (base64) and read the `sub` claim. This is the userId for `debug_overwrites.json`.
+
+## References
+
+- [process.md](process.md) — capability overview + happy-path walkthrough using refresh
+- [../../solution-resources.md](../../solution-resources.md) § Refresh Mechanics, § Debug Overwrites

package/skills/uipath-agents/references/lowcode/critical-rules.md

@@ -0,0 +1,76 @@
+# Critical Rules and Anti-Patterns
+
+These rules are the canonical source for low-code agent authoring. Capability files cross-reference back here; they do not restate rules.
+
+## Critical Rules (22)
+
+1. **Edit JSON files directly, except CLI-managed memory features** — the CLI supports `init` (scaffold), `validate` (read-only check), `migrate` (apply writes + regenerate `.agent-builder/`), and `memory` (writes memory feature files). Agent configuration (prompts, schemas, settings) is done by editing `agent.json` and `entry-points.json`. Resources (tools, contexts, escalations) are added as individual files in `resources/{ResourceName}/resource.json` inside the agent project directory — **not** inline in `agent.json`. Memory spaces are added with `uip agent memory` and live in `features/{FeatureName}/feature.json`. The root `agent.json` should not contain `resources` or manually-authored memory feature entries. The `migrate` command reads these files and generates `.agent-builder/agent.json` which inlines them.
+
+2. **Validate and migrate after every bulk of edits** — run `uip agent validate --output json` to check, then `uip agent migrate --output json` to write any pending migrations and regenerate `.agent-builder/`. Validate is read-only (never writes files); migrate applies writes only when all checks pass. Always run both in sequence after a cohesive set of related changes.
+
+3. **Use `--output json`** on all `uip` commands when parsing output.
+
+4. **Keep schemas in sync** — `inputSchema` and `outputSchema` in `agent.json` must exactly mirror `input` and `output` in `entry-points.json`. Update both when adding or removing fields.
+
+5. **Use `{{input.fieldName}}` syntax** in user message templates. Do not use `$vars` or `=js:` expressions — those are flow syntax, not agent syntax.
+
+6. **Keep contentTokens in sync with content** — every message has both a `content` string and a `contentTokens` array. Update both when editing. See [agent-definition.md](agent-definition.md) § contentTokens Construction.
+
+7. **Do not manually create or edit `.agent-builder/`** — it is generated by `uip agent migrate` and managed by Studio Web. Never create or modify `.agent-builder/` files by hand.
+
+8. **Do not publish or deploy without user consent** — ask before running `uip solution upload`, `uip solution publish`, or `uip solution deploy`.
+
+9. **Do not modify `projectId`** — auto-generated by `uip agent init`.
+
+10. **Solution must exist first** — create one with `uip solution init` before scaffolding an agent.
+
+11. **Set `folderPath` to the literal `Folder` returned by `uip solution resource list`.** Applies to both local (`Source: "Local"`) and external (`Source: "Remote"`) resources, and to tool `properties.folderPath`, context-index top-level `folderPath`, escalation `channel.properties.folderName`, and guardrail escalation `action.app.folderName`. Local resources typically carry `"solution_folder"` (their declared folder in the solution); external resources carry the human-readable, slash-separated Orchestrator folder (e.g., `"Shared"`, `"Shared/Sales/Region-EU"`). The author writes the value verbatim into `resource.json` (or into the guardrail action under `agent.json`); `uip agent migrate` propagates it into `bindings_v2.json` as `folderPath` (App resources translate `folderName` → binding `folderPath`). See [capabilities/process/process.md](capabilities/process/process.md) § Tool resource.json Shape.
+
+12. **Tools carry a `location` field.** Use `"solution"` when the row from `uip solution resource list` has `Source: "Local"` (resource is in the same solution); use `"external"` when `Source: "Remote"` (already deployed in Orchestrator). All other resource fields (`type`, `referenceKey`, `folderPath`, schemas, `exampleCalls`) follow the same rules in both cases. Connection (Integration Service) bindings are bound by `connection.id` and are exempt — no `folderPath` propagation.
+
+13. **Process tools require solution-level resource files and `debug_overwrites.json`.** Whether local or external, you need the agent-level `resources/{ToolName}/resource.json`, solution-level files under `resources/solution_folder/`, AND a `userProfile/<userId>/debug_overwrites.json` for folder resolution. `uip solution resource refresh` generates these from the bindings; for in-solution agents the package + process declarations are pre-created when the project is registered with the solution (auto-registered by `uip agent init` when run inside the solution directory; falls back to `uip solution project add` if registration was `Skipped` or `Failed`), and refresh resolves the binding against them. Without these, Studio Web will show "resource is missing in this environment". See [capabilities/process/solution-files.md](capabilities/process/solution-files.md).
+
+14. **Never manually edit `storageVersion`.** It is managed by `uip agent migrate` (which writes the latest version on success) and by Studio Web on import. `uip agent validate` reports `MigrationPending: true` if the file is behind, but does not write. If validate reports a `storageVersion` newer than supported, upgrade uipcli rather than editing the field by hand.
+
+15. **Inline agents in flows use `uipath.agent.autonomous` nodes.** The node's `inputs.source` references the inline agent's `projectId` UUID. Attached resource nodes (`uipath.agent.resource.tool.*`, `uipath.agent.resource.escalation`, `uipath.agent.resource.context.*`) use the same `inputs.source` convention to reference their `<RES_UUID>` subdirectory under `<projectId>/resources/`. The definition still declares `model.source: true`, but flow-core hoists the source identity onto `inputs.source` for the node instance; no node instance carries an instance `model` block. The agent definition lives in a subdirectory inside the flow project. See [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md).
+
+16. **Never invoke other skills automatically.** If the user needs flow operations, tell them to use the `uipath-maestro-flow` skill.
+
+17. **Read [capabilities/guardrails/guardrails.md](capabilities/guardrails/guardrails.md) before authoring guardrail JSON.** The schema uses discriminator fields (`$guardrailType`, `$actionType`, `$parameterType`, `$ruleType`, `$selectorType`) that cannot be guessed. Configure guardrails at the agent.json root `guardrails` array only.
+
+18. **`{{input.<file-field>}}` exposes metadata only.** When an input field is a `job-attachment`, the variable token renders only `ID`, `FullName`, `MimeType`, and `Metadata` into the prompt — not the file contents. To let the agent read contents, configure a file-handling built-in tool (e.g. `analyze-attachments`) and instruct the agent to call it. See [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md).
+
+19. **`job-attachment` schema is canonical — copy verbatim.** Declare file fields as `{ "$ref": "#/definitions/job-attachment" }` and place the canonical block under `definitions`. `x-uipath-resource-kind: "JobAttachment"` is required. Same schema for input and output fields. See [agent-definition.md](agent-definition.md) § File Attachments.
+
+20. **Built-in tools require explicit configuration.** Tools like `analyze-attachments` are not implicitly available — add them as `resources/{Name}/resource.json` with `type: "internal"` and `properties.toolType: "<kebab-lowercase-id>"`. The `toolType` discriminator is fixed per tool — copy from the capability reference, do not invent. See [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md).
+
+21. **Built-in tools need no solution-level files and no resource refresh.** Unlike external process tools, built-in tools (`type: "internal"`) are self-contained at the agent level. Do not run `uip solution resource refresh` for them; do not author solution-level resource files. Validate the agent and bundle.
+
+22. **Use `uip agent memory` for memory spaces and seed items.** The memory commands own `features/{FeatureName}/feature.json`, `.agent-builder/agent.json`, memory item type validation, and generated `memorySpace` bindings. Attach existing memory spaces by `--memory-space` plus literal `--folder-path`; seed items require `--memory-type episodic|escalation`, and episodic seed items require `--feedback-id`. Run `uip agent validate --output json`, `uip agent migrate --output json`, and then `uip solution resource refresh --output json` after memory changes in a solution. See [capabilities/memory/memory.md](capabilities/memory/memory.md).
+
+## What NOT to Do (24)
+
+1. **Do not manually create or edit `.agent-builder/` files** — it is generated by `uip agent migrate` and managed by Studio Web. Never create or modify these files by hand.
+2. **Do not use `=js:` or `$vars` in agent messages** — use `{{input.fieldName}}` only
+3. **Do not skip schema sync** — agent.json and entry-points.json must match
+4. **Do not skip validation after a bulk of related edits** — validate after each cohesive set of changes (not after every line, but always before moving on to a new capability or publishing)
+5. **Do not publish/deploy without validating** — always validate first
+6. **Do not forget contentTokens** — editing `content` without updating `contentTokens` causes rendering issues
+7. **Do not forget `uip solution resource refresh` after adding a process tool** — applies to both local and external. Creating only the agent-level `resources/{ToolName}/resource.json` is not enough. After `uip agent migrate` generates `bindings_v2.json`, run `uip solution resource refresh` from the solution root to import the bindings into the solution. For `Connection` bindings refresh also generates `debug_overwrites.json`. For `Process`, `App`, and `Index` bindings refresh imports the resource but does not hand-write the rich solution-level files — check the output and hand-author missing files per [capabilities/process/solution-files.md](capabilities/process/solution-files.md).
+8. **`uip solution resource list` returns identity only (Source/Key/Name/Type/Folder/FolderKey)** — for the full configuration run `uip solution resource get <KEY> --output json` and read `Data.spec`. Applies to `--kind Process` (argument schemas, package keys, entry-point IDs — see [capabilities/process/process.md § Discovery](capabilities/process/process.md#discovery)) and `--kind Index` (data source type, storage bucket reference — see [capabilities/context/index.md § Discovery](capabilities/context/index.md#discovery)).
+9. **Do not copy-paste UUIDs from one resource to another** — every resource (including each guardrail) needs a unique UUID.
+10. **Do not bump `storageVersion` manually** — breaks packager compatibility.
+11. **Do not call raw Automation.Solutions REST APIs** — always use `uip solution` commands.
+12. **Do not camelCase `contextType` or `retrievalMode` values** — write `"datafabricentityset"`, `"deeprag"`, `"batchtransform"` (all lowercase). `uip agent validate` accepts camelCase but Studio Web silently drops the resource from the agent UI on import.
+13. **Do not pass `--for-low-code-agents` to `uip is connectors list` or `uip is activities list`** — this flag has been removed. Run the commands without it and filter yourself if needed.
+14. **Do not omit discriminator fields in guardrails** — every action needs `$actionType` (not `type`), every validator parameter needs `$parameterType` and `id` (not `name`), every custom rule needs `$ruleType`, every field selector needs `$selectorType`. Missing any discriminator causes `uip agent validate` to fail.
+15. **Do not use lowercase scope values in guardrails** — use `"Agent"`, `"Llm"`, `"Tool"` (PascalCase), not `"agent"`, `"llm"`, `"tool"`.
+16. **Always include `"guardrail": { "policies": [] }` in every tool resource.json, and never populate `policies` with entries** — the field must be present for backward-compatible solution loading; omitting it causes the runtime to fail. All guardrails are configured at the agent.json root `guardrails` array with `selector.scopes` and `selector.matchNames`.
+17. **Do not expect `uip solution resource refresh` to wire non-StorageBucket index data sources** — GoogleDrive/OneDrive/Dropbox/Confluence/Attachments indexes, `attachments` contexts, and `datafabricentityset` contexts are not auto-generated. Refresh warns + skips them; any solution-level files for these must be hand-authored. See [capabilities/context/index.md](capabilities/context/index.md).
+18. **Do not add a Tool-scoped guardrail before the tool exists** — run `uip agent tool list` first and confirm every name in `selector.matchNames` is present. `uip agent validate` will fail with an error if a guardrail targets a tool that has not been added to the agent.
+19. **Set `folderPath` on process tool resources to the literal `Folder` from `uip solution resource list`** — applies whether `Source` is `Local` or `Remote`. `uip agent validate` reads it from the agent-level `resource.json` during the schema check; `uip agent migrate` propagates it verbatim into `bindings_v2.json`. The same value goes into the matching solution-level process declaration's `folders[].fullyQualifiedName`.
+20. **Do not hand-edit `bindings_v2.json`** — the file is generated by `uip agent migrate` from the agent-level `resource.json` (including `folderPath`). Edit `resource.json` and re-run migrate; never patch the binding directly.
+21. **Do not pass attachments via the `uip` CLI** — runtime file inputs are not supported by `uip agent run` or solution-level CLI run paths. Test attachment-aware agents from Studio Web or via Orchestrator job invocation.
+22. **Do not assume `{{input.<job-attachment>}}` lets the agent read the file** — it renders metadata only. Pair the file field with a file-handling built-in tool (e.g. `analyze-attachments`) so the agent has a way to read contents.
+23. **Do not run final inline-agent validation or migration before flow graph edits for inline-in-flow agents** — direct `.flow` authoring of the inline-agent node, capability-resource nodes, and edges is owned by the `uipath-maestro-flow` skill. Always run `uip agent validate --inline-in-flow` and then `uip agent migrate --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` **after** those flow graph edits are complete. Migrate is what propagates the inline agent's bindings into the flow project's `bindings_v2.json`; without it, `uip solution resource refresh` cannot discover them. Never hand-edit `bindings_v2.json`. See [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md).
+24. **Do not hand-edit memory feature files for routine changes** — use `uip agent memory add/list/remove` and `uip agent memory item add/list/remove`. Hand-writing `features/{Name}/feature.json`, `.agent-builder/agent.json`, or `bindings_v2.json` can desynchronize generated state and skip CLI validation for search mode, field weights, metadata JSON, and memory item type.