@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-coded-apps/references/sdk/orchestrator.md

@@ -1,221 +1,16 @@
-# Orchestrator Reference
+# Orchestrator — Traps & Server Behavior
 
-## Imports
+Signatures/params/examples: `dist/assets/index.d.ts`, `dist/queues/index.d.ts`, `dist/buckets/index.d.ts`, `dist/processes/index.d.ts`, `dist/jobs/index.d.ts`, `dist/attachments/index.d.ts`. Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-```typescript
-import { Assets } from '@uipath/uipath-typescript/assets';
-import { Queues } from '@uipath/uipath-typescript/queues';
-import { Buckets } from '@uipath/uipath-typescript/buckets';
-import { Processes } from '@uipath/uipath-typescript/processes';
-import { Jobs } from '@uipath/uipath-typescript/jobs';
-import { Attachments } from '@uipath/uipath-typescript/attachments';
-```
-
-## Note: Folder-Scoped Services
-
-Assets, Queues, Buckets, and Processes are folder-scoped. Many methods require a `folderId` parameter.
-
-**Bound methods**: `Jobs.getById()` and `Jobs.getAll()` items return response objects with attached methods (`getOutput()`, `stop()`, `resume()`, `restart()`). Assets, Queues, Buckets, Processes, and Attachments responses do **not** have attached methods — use the service directly.
-
-## `getByName` folder identifiers
-
-`Assets.getByName` and `Processes.getByName` accept `FolderScopedOptions` — supply one of `folderId`, `folderKey`, or `folderPath` (e.g., `'Shared/Finance'`). If multiple are supplied, server precedence is `folderPath` > `folderKey` > `folderId`.
-
-## Types to Import
-
-```typescript
-// Assets
-import type {
-  AssetGetResponse,
-  AssetGetAllOptions,
-  AssetGetByIdOptions,
-  AssetGetByNameOptions,
-  CustomKeyValuePair,
-} from '@uipath/uipath-typescript/assets';
-
-// Queues
-import type {
-  QueueGetResponse,
-  QueueGetAllOptions,
-  QueueGetByIdOptions,
-} from '@uipath/uipath-typescript/queues';
-
-// Buckets
-import type {
-  BucketGetResponse,
-  BucketGetAllOptions,
-  BucketGetByIdOptions,
-  BucketGetByNameOptions,
-  BucketGetFilesOptions,
-  BucketFile,
-  BucketGetFileMetaDataWithPaginationOptions,
-  BucketGetFileMetaDataOptions,
-  BucketGetReadUriOptions,
-  BucketGetUriResponse,
-  BucketUploadFileOptions,
-  BucketUploadResponse,
-  BucketDeleteFileOptions,
-  BlobItem,
-} from '@uipath/uipath-typescript/buckets';
-
-// Processes
-import type {
-  ProcessGetResponse,
-  ProcessGetAllOptions,
-  ProcessGetByIdOptions,
-  ProcessGetByNameOptions,
-  ProcessStartRequest,
-  ProcessStartResponse,
-} from '@uipath/uipath-typescript/processes';
-
-// Jobs
-import type {
-  JobGetResponse,
-  JobGetAllOptions,
-  JobGetByIdOptions,
-  JobStopOptions,
-  JobResumeOptions,
-  JobMethods,
-} from '@uipath/uipath-typescript/jobs';
-
-// Attachments
-import type {
-  AttachmentResponse,
-  AttachmentGetByIdOptions,
-} from '@uipath/uipath-typescript/attachments';
-```
-
-## Enums
-
-```typescript
-// Assets
-import {
-  AssetValueScope,   // Global, PerRobot
-  AssetValueType,    // DBConnectionString, HttpConnectionString, Text, Bool, Integer, Credential, WindowsCredential, KeyValueList, Secret
-} from '@uipath/uipath-typescript/assets';
-
-// Buckets
-import {
-  BucketOptions,     // None, ReadOnly, AuditReadAccess, AccessDataThroughOrchestrator
-} from '@uipath/uipath-typescript/buckets';
-
-// Processes
-import {
-  PackageType,       // Undefined, Process, ProcessOrchestration, WebApp, Agent, TestAutomationProcess, Api, MCPServer, BusinessRules
-  JobPriority,       // Low, Normal, High
-  StartStrategy,     // All, Specific, RobotCount, JobsCount, ModernJobsCount
-  TargetFramework,   // Legacy, Windows, Portable
-  RobotSize,         // Small, Standard, Medium, Large
-  PackageSourceType, // Manual, Schedule, Queue, StudioWeb, ...
-  StopStrategy,      // SoftStop, Kill
-} from '@uipath/uipath-typescript/processes';
-```
-
-## Assets Service (Scopes: `OR.Assets` or `OR.Assets.Read`)
-
-### getAll(options?: AssetGetAllOptions)
-
-Returns `NonPaginatedResponse<AssetGetResponse>` or `PaginatedResponse<AssetGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`.
-
-### getById(id: number, folderId: number, options?: AssetGetByIdOptions)
-
-Returns `Promise<AssetGetResponse>`. The `folderId` is required.
-
-### getByName(name: string, options: AssetGetByNameOptions)
-
-Returns `Promise<AssetGetResponse>`. Resolves an asset by display name within a folder. Supply one of `folderId` (number), `folderKey` (GUID string), or `folderPath` (e.g., `'Shared/Finance'`). Throws `NotFoundError` if no asset matches.
-
-```typescript
-await assets.getByName('ApiKey', { folderId: 123 });
-await assets.getByName('ApiKey', { folderKey: '5f6dadf1-3677-49dc-8aca-c2999dd4b3ba' });
-await assets.getByName('ApiKey', { folderPath: 'Shared/Finance', expand: 'keyValueList' });
-```
-
-`AssetGetResponse` fields: `key`, `name`, `id`, `canBeDeleted`, `valueScope`, `valueType`, `value`, `credentialStoreId`, `keyValueList`, `hasDefaultValue`, `description`, `foldersCount`, `lastModifiedTime`, `createdTime`, `creatorUserId`. **Note:** Additional fields may be available. Check the TypeScript types for the complete list.
-
-## Queues Service (Scopes: `OR.Queues` or `OR.Queues.Read`)
-
-### getAll(options?: QueueGetAllOptions)
-
-Returns `NonPaginatedResponse<QueueGetResponse>` or `PaginatedResponse<QueueGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
-
-### getById(id: number, folderId: number, options?: QueueGetByIdOptions)
-
-Returns `Promise<QueueGetResponse>`. The `folderId` is required.
-
-`QueueGetResponse` fields: `key`, `name`, `id`, `description`, `maxNumberOfRetries`, `acceptAutomaticallyRetry`, `retryAbandonedItems`, `enforceUniqueReference`, `encrypted`, `createdTime`, `slaInMinutes`, `riskSlaInMinutes`, `folderId`, `folderName`.
-
-## Buckets Service (Scopes: `OR.Buckets` or `OR.Buckets.Read`; `OR.Buckets.Write` for `deleteFile`)
-
-### getAll(options?: BucketGetAllOptions)
-
-Returns `NonPaginatedResponse<BucketGetResponse>` or `PaginatedResponse<BucketGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
-
-### getById(bucketId: number, folderId: number, options?: BucketGetByIdOptions)
-
-Returns `Promise<BucketGetResponse>`.
-
-`BucketGetResponse` fields: `id`, `name`, `description`, `identifier`, `storageProvider`, `storageContainer`, `options`, `foldersCount`.
-
-### getByName(name: string, options?: BucketGetByNameOptions)
-
-Returns `Promise<BucketGetResponse>`. Resolves a bucket by name within a folder. `BucketGetByNameOptions` is `FolderScopedOptions` — supply one of `folderId`, `folderKey`, or `folderPath` (same precedence as Assets/Processes) plus optional `expand` / `select`. Throws `NotFoundError` if no bucket matches.
-
-### getFiles(bucketId: number, options?: BucketGetFilesOptions)
-
-Returns `NonPaginatedResponse<BucketFile>` or `PaginatedResponse<BucketFile>`. Folder-scoped (`folderId` / `folderKey` / `folderPath`); supports regex filtering, query options, and pagination. Each `BucketFile` includes `isDirectory` so callers can distinguish folders from files. **Note:** Additional fields may be available — check the TypeScript types.
-
-> **`getFiles` vs `getFileMetaData`.** `getFiles` returns `BucketFile` items (folder-aware, supports regex filtering) and is folder-scoped via `FolderScopedOptions`. `getFileMetaData` returns flat `BlobItem` items by `prefix` and takes a positional `folderId`. Prefer `getFiles` for directory-style browsing.
-
-### getFileMetaData(bucketId: number, folderId: number, options?: BucketGetFileMetaDataWithPaginationOptions)
-
-Returns `NonPaginatedResponse<BlobItem>` or `PaginatedResponse<BlobItem>`. Options: `{ prefix?: string }` plus pagination. Each `BlobItem` has: `path`, `contentType`, `size`, `lastModified`.
-
-### uploadFile(options: BucketUploadFileOptions)
-
-Returns `Promise<BucketUploadResponse>` with `{ success, statusCode }`. Options: `{ bucketId, folderId, path, content: Blob | Uint8Array<ArrayBuffer> | File }`.
-
-### getReadUri(options: BucketGetReadUriOptions)
-
-Returns `Promise<BucketGetUriResponse>` with `{ uri, httpMethod, requiresAuth, headers }`. Options: `{ bucketId, folderId, path, expiryInMinutes? }`.
-
-### deleteFile(bucketId: number, path: string, options?: BucketDeleteFileOptions)
-
-Returns `Promise<void>`. Deletes a single file from the bucket by `path`. `BucketDeleteFileOptions` is folder-scoped (`folderId` / `folderKey` / `folderPath`). Requires `OR.Buckets` or `OR.Buckets.Write`.
+> **Scope pairing warning:** `Jobs.getOutput()` resolves file-type output arguments through the Attachments service internally — the app needs `OR.Folders` (or `OR.Folders.Read`) **in addition to** its Jobs scope, or the call 403s. Do not assume one scope per service; check the shipped table per method.
 
-## Processes Service (Scopes: `OR.Execution` / `OR.Execution.Read`, `OR.Jobs` / `OR.Jobs.Write` for start)
+## Job classification — agent vs process vs app
 
-### getAll(options?: ProcessGetAllOptions)
+An agent job is identified by **`packageType === 'Agent'`** — both when reading response objects and in OData `filter` strings (the SDK rewrites SDK field names to API names in `filter`/`orderby`/`select`/`expand` automatically).
 
-Returns `NonPaginatedResponse<ProcessGetResponse>` or `PaginatedResponse<ProcessGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`.
-
-### getById(id: number, folderId: number, options?: ProcessGetByIdOptions)
-
-Returns `Promise<ProcessGetResponse>`.
-
-### getByName(name: string, options: ProcessGetByNameOptions)
-
-Returns `Promise<ProcessGetResponse>`. Resolves a process release by name within a folder. Supply one of `folderId`, `folderKey`, or `folderPath`. Throws `NotFoundError` if no process matches.
-
-```typescript
-await processes.getByName('MyProcess', { folderPath: 'Shared/Finance', expand: 'entryPoints' });
-```
-
-`ProcessGetResponse` fields: `key`, `packageKey`, `packageVersion`, `isLatestVersion`, `description`, `name`, `packageType`, `targetFramework`, `robotSize`, `autoUpdate`, `id`, `folderId`, `folderName`, `folderKey`, `createdTime`, `lastModifiedTime`.
-
-### start(request: ProcessStartRequest, folderId: number, options?: RequestOptions)
-
-Returns `Promise<ProcessStartResponse[]>`. The `request` must include either `processKey` or `processName`. Optional fields: `strategy`, `robotIds`, `jobsCount`, `inputArguments`, `jobPriority`.
-
-`ProcessStartResponse` fields: `key`, `startTime`, `endTime`, `state`, `source`, `processName`, `type`, `id`, `folderId`.
-
-## Jobs Service (Scopes: `OR.Jobs` or `OR.Jobs.Read`)
-
-### getAll(options?: JobGetAllOptions)
-
-Returns `NonPaginatedResponse<JobGetResponse>` or `PaginatedResponse<JobGetResponse>`. Options extend `RequestOptions & PaginationOptions & { folderId?: number }`. Supports `filter`, `orderby`, `expand`, `select`. Rows are on `.items`.
+> **Do NOT use `sourceType` to find agent jobs.** `sourceType` (raw `Source` / `JobSourceType`) is the **trigger origin** — `Manual`, `Schedule`, `Queue`, `Agent`, `Apps`, `HttpTrigger`, … An agent job can be triggered manually (`sourceType: "Manual"`), and `sourceType: "Agent"` only means "started by an agent source," which is a different thing. Filtering on `sourceType === 'Agent'` is wrong in both directions.
 
-**Example response** (`.items`) — an agent job next to a standard RPA job. The agent job is `packageType: "Agent"` (the SDK maps raw `ProcessType` → `packageType`). Note `sourceType` is the *trigger origin* (here both happen to differ) and does NOT identify an agent — see § Job classification:
+**Example response** (`Jobs.getAll()` `.items`) — an agent job next to a standard RPA job. The agent job is `packageType: "Agent"`. Note `sourceType` is the *trigger origin* (here both happen to differ) and does NOT identify an agent:
 
 ```json
 {
@@ -239,60 +34,18 @@ Returns `NonPaginatedResponse<JobGetResponse>` or `PaginatedResponse<JobGetRespo
 }
 ```
 
-### getById(id: string, folderId: number, options?: JobGetByIdOptions)
-
-Returns `Promise<JobGetResponse>`. The `folderId` is required. **Note:** `id` is a `string` here (not a `number` like Assets/Queues/Processes).
-
-### getOutput(jobKey: string, folderId: number)
-
-Returns `Promise<Record<string, unknown> | null>` — the job's parsed output arguments, or `null` if unavailable. Use after a job has finished; output is not populated while the job is still running.
-
-### stop(jobKeys: string[], folderId: number, options?: JobStopOptions)
-
-Returns `Promise<void>`. Stops one or more jobs (pass an array even for a single job). Throws if any keys cannot be resolved. `JobStopOptions`: `{ strategy?: StopStrategy }` — `StopStrategy.SoftStop` (default, graceful) or `StopStrategy.Kill` (immediate).
-
-### resume(jobKey: string, folderId: number, options?: JobResumeOptions)
+Job latency ← `endTime − startTime` (both timestamps; `endTime` is null while `Running` — a server behavior the types show only as `string | null`).
 
-Returns `Promise<void>`. Resumes a job currently in `Suspended` state. `JobResumeOptions`: `{ inputArguments?: Record<string, unknown> }`.
+Server-side filters (SDK field names — the SDK rewrites them to API names):
+- Agent jobs: `getAll({ filter: "packageType eq 'Agent'", orderby: 'createdTime desc' })`
+- Faulted agent jobs: `getAll({ filter: "State eq 'Faulted' and packageType eq 'Agent'" })`
+- Reading results: `result.items.filter(j => j.packageType === 'Agent')`
 
-### restart(jobKey: string, folderId: number)
+### OData filter field names
 
-Returns `Promise<JobGetResponse>` — a **new** job with a new `key`, in `Pending` state. The original job must be in a final state (`Successful`, `Faulted`, or `Stopped`). Inputs are inherited from the original.
-
-`JobGetResponse` fields: `key`, `id`, `state`, `createdTime`, `startTime`, `endTime`, `lastModifiedTime`, `resumeTime`, `processName`, `entryPointPath`, `processVersionId`, `hostMachineName`, `inputArguments`, `outputArguments`, `environmentVariables`, `type`, `sourceType`, `packageType`, `runtimeType`, `serverlessJobType`, `jobPriority`, `specificPriorityValue`, `stopStrategy`, `remoteControlAccess`, `batchExecutionKey`, `parentJobKey`, `traceId`, `parentSpanId`, `errorCode`, `jobError`, `subState`, `machine`, `robot`, `process`. The `machine`, `robot`, and `process` fields are populated only when requested via `expand`.
-
-### Job classification — agent vs process vs app
-
-An agent job is identified by **`packageType === 'Agent'`** on the SDK response object. The SDK's `JobMap` renames the raw API field `ProcessType → packageType`, so a raw job with `ProcessType: "Agent"` arrives as `packageType: "Agent"`.
-
-| Where | Field | Agent job value |
-|-------|-------|-----------------|
-| SDK response object (`fnBody` reads this) | `packageType` | `"Agent"` |
-| OData server-side `filter` string (raw API name) | `ProcessType` | `"Agent"` |
-
-> **Do NOT use `sourceType` to find agent jobs.** `sourceType` (raw `Source` / `JobSourceType`) is the **trigger origin** — `Manual`, `Schedule`, `Queue`, `Agent`, `Apps`, `HttpTrigger`, … An agent job can be triggered manually (`sourceType: "Manual"`), and `sourceType: "Agent"` only means "started by an agent source," which is a different thing. Filtering on `sourceType === 'Agent'` is wrong in both directions.
+The SDK rewrites SDK field names inside `filter` / `orderby` / `select` / `expand` to raw API names before sending (`processName → releaseName`, `createdTime → creationTime`, `packageType → processType`); raw API names pass through unchanged, so either spelling works. `folderId` is never a `$filter` field — folder scoping travels via header.
 
-Field mappings (raw → SDK, from `JobMap`): `releaseName → processName`, `creationTime → createdTime`, `organizationUnitId → folderId`. Job latency ← `endTime − startTime` (both timestamps; `endTime` is null while `Running`).
-
-Server-side filters (use the raw field name `ProcessType` in the OData string):
-- Agent jobs: `getAll({ filter: "ProcessType eq 'Agent'", orderby: 'CreationTime desc' })`
-- Faulted agent jobs: `getAll({ filter: "State eq 'Faulted' and ProcessType eq 'Agent'" })`
-- Reading results: `result.items.filter(j => j.packageType === 'Agent')` (client-side, mapped field name)
-
-#### Filterable vs read-only Job fields
-
-A field appearing in the response does **NOT** make it valid in an OData `$filter`. The SDK's mapped (renamed) response fields are **read-only** — filtering on them throws `Invalid OData query options … Could not find a property named '<field>'` at request time (invisible to `tsc`).
-
-| Read-only (response only — NEVER in `$filter`) | Filter on the raw field instead |
-|---|---|
-| `processName` (← `releaseName`) | match **client-side**: `items.filter(j => j.processName === name)` |
-| `createdTime` (← `creationTime`) | `CreationTime` (e.g. `orderby: 'CreationTime desc'`) |
-| `folderId` (← `organizationUnitId`) | folder is scoped via header, not `$filter` |
-| `packageType` (← `ProcessType`) | `ProcessType` |
-
-Safe `$filter` fields: **`ProcessType`**, **`State`**, **`CreationTime`**, **`StartTime`**. To find a specific agent's jobs, filter `ProcessType eq 'Agent'` and match the name **client-side** on `processName` — there is no server-side name filter.
-
-#### Recipe — jobs for a named agent → its most-recent trace's spans
+### Recipe — jobs for a named agent → its most-recent trace's spans
 
 The bridge from a clicked agent to its spans (e.g. a `rowLink` table's `fetchDetailByKey`):
 
@@ -302,56 +55,36 @@ import type { MetricDetailByKeyFn } from '@/lib/metric-contract'
 export const fetchDetailByKey: MetricDetailByKeyFn = async (sdk, agentName) => {
   const { Jobs } = await import('@uipath/uipath-typescript/jobs')
   const { AgentTraces } = await import('@uipath/uipath-typescript/traces')
-  const jobs = (await new Jobs(sdk).getAll({ filter: "ProcessType eq 'Agent'", orderby: 'CreationTime desc' }))?.items ?? []
-  const job = jobs.find(j => j.processName === agentName)   // client-side match — processName is read-only
+  const jobs = (await new Jobs(sdk).getAll({ filter: "packageType eq 'Agent'", orderby: 'createdTime desc' }))?.items ?? []
+  const job = jobs.find(j => j.processName === agentName)   // name match is client-side (no server-side name filter)
   if (!job?.traceId) return []
   return await new AgentTraces(sdk).getSpansByTraceId(job.traceId)   // Job carries traceId (see traces.md)
 }
 ```
 
-## Job-Attached Methods (JobMethods)
-
-Returned by `getById()` and `getAll()` items on each `JobGetResponse`. These are bound to the job's `key` and `folderId`, so you don't need to pass them again:
-
-- `job.getOutput()` -> `Promise<Record<string, unknown> | null>`
-- `job.stop(options?)` -> `Promise<void>`
-- `job.resume(options?)` -> `Promise<void>`
-- `job.restart()` -> `Promise<JobGetResponse>` (new job)
-
-```typescript
-const all = await jobs.getAll({ folderId, pageSize: 20 });
-const running = all.items.find(j => j.state === 'Running');
-if (running) await running.stop();             // bound — no folderId needed
-const completed = all.items.find(j => j.state === 'Successful');
-if (completed) {
-  const output = await completed.getOutput();   // bound
-  const newJob = await completed.restart();     // bound
-}
-```
-
-## Attachments Service (Scopes: `OR.Folders` or `OR.Folders.Read`)
+## Bucket file listing — which method
 
-Standalone service for retrieving an Orchestrator attachment's metadata and a signed URL for downloading the blob. Coded Action Apps use this to resolve a `type: "file"` input — the file reference handed in by the automation (Maestro / Agent / RPA) — into downloadable bytes. `Jobs.getOutput()` also uses it internally to resolve file-type output arguments — if you call `Jobs.getOutput()` you must add `OR.Folders` (or `OR.Folders.Read`) to the app's scopes in addition to `OR.Jobs`.
+`getFiles` (folder-aware `BucketFile` items, regex filtering) vs `getFileMetaData` (flat `BlobItem` list by `prefix`): prefer **`getFiles`** for directory-style browsing. Neither method's JSDoc mentions the other. Note `JobGetResponse.process` is populated only via `expand` (its JSDoc, unlike `machine`/`robot`, does not say so).
 
-This service exposes **only** `getById` — there is no `getAll`, no create, and no delete.
+## Attachments Service
 
-### getById(id: string, options?: AttachmentGetByIdOptions)
-
-Returns `Promise<AttachmentResponse>`. `id` is the attachment **UUID** (string) — not a number. Throws `ValidationError` if `id` is empty. `AttachmentGetByIdOptions` supports OData `expand` / `select`.
-
-`AttachmentResponse` fields: `id`, `name`, `jobKey?`, `attachmentCategory?`, `lastModifiedTime?`, `lastModifierUserId?`, `createdTime?`, `creatorUserId?`, `blobFileAccess: BucketGetUriResponse` (the signed URL + headers — `{ uri, httpMethod, requiresAuth, headers }`).
-
-Resolve a `file`-typed input to its bytes. Respect `requiresAuth` — when `true`, pass `headers` on the download request:
+Cross-artifact role the types don't show: Coded Action Apps resolve a `type: "file"` input — the file reference handed in by the automation (Maestro / Agent / RPA) — into bytes via `Attachments.getById()` → `blobFileAccess` (signed URL + headers). `Jobs.getOutput()` uses the same service internally for file-type outputs (see scope pairing warning above). When `blobFileAccess.requiresAuth` is `true`, pass `blobFileAccess.headers` on the download request.
 
 ```typescript
 import { Attachments } from '@uipath/uipath-typescript/attachments';
 
-const attachments = new Attachments(sdk);
-const attachment = await attachments.getById('<attachmentId>');
-// Download the blob using the signed URI
+const attachment = await new Attachments(sdk).getById('<attachmentId>');
 const blob = await fetch(attachment.blobFileAccess.uri).then(r => r.blob());
 ```
 
+## Folder scoping — deploy folder is auto-injected; don't enumerate
+
+There is **no `Folders` service** — no folder-listing/enumeration API exists (only the internal `FolderScopedService` base). Don't hunt for one.
+
+A deployed coded app is auto-scoped to the folder it was deployed into: the platform injects `<meta name="uipath:folder-key">` at deploy, the SDK loads it at init (`loadFromMetaTags()`), and every folder-scoped call falls back to it (`X-UIPATH-FolderKey` header) when the call passes no folder. **Default: pass no folder → calls target the app's own folder.** Target a different folder by passing an explicit `folderId` / `folderKey` / `folderPath` (it takes precedence; bridge a bare `folderKey` to `folderId` via [Bridging folderKey ↔ folderId](#bridging-folderkey--folderid)). No injected meta tag (some local dev setups) → no fallback, so pass an explicit folder.
+
+> **Invisible in the type surface.** `folderKey` is deliberately kept off the public `UiPathConfig`, so reading the `.d.ts` will not reveal this fallback mechanism — it is exactly the kind of behavior this file exists to record.
+
 ## Bridging folderKey ↔ folderId
 
 Maestro services return `folderKey` (GUID string), but Orchestrator services like `Processes.start()` require `folderId` (number). These are **completely different identifiers** — `parseInt(folderKey)` gives `NaN`.
@@ -405,30 +138,3 @@ for (const p of orchProcesses.items) {
 }
 // Use: folderMap.get(maestroProcess.folderKey) → folderId
 ```
-
-## Usage Example
-
-```typescript
-import { useMemo } from 'react';
-import { useAuth } from '../hooks/useAuth';
-import { Assets } from '@uipath/uipath-typescript/assets';
-import { Processes } from '@uipath/uipath-typescript/processes';
-import type { ProcessStartRequest } from '@uipath/uipath-typescript/processes';
-
-function OrchestratorActions({ folderId }: { folderId: number }) {
-  const { sdk } = useAuth();
-  const assets = useMemo(() => new Assets(sdk), [sdk]);
-  const processes = useMemo(() => new Processes(sdk), [sdk]);
-
-  const listAssets = async () => {
-    const result = await assets.getAll({ folderId, pageSize: 10 });
-    return result.items;
-  };
-
-  const startProcess = async (processKey: string) => {
-    const request: ProcessStartRequest = { processKey };
-    const jobs = await processes.start(request, folderId);
-    return jobs;
-  };
-}
-```

package/skills/uipath-coded-apps/references/sdk/pagination.md

@@ -1,11 +1,11 @@
-# Pagination Reference
+# Pagination — Server Behavior & Patterns
 
-> **Foot-gun: every "list" call returns ONE page, even when you pass no pagination options.** `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. all make exactly one HTTP call. Whether the response is typed as `PaginatedResponse` or `NonPaginatedResponse` is purely about whether you passed pagination options — it does NOT control how many rows you get back.
->
-> - `getAll()` (no options) → `NonPaginatedResponse` → SDK sends no `pageSize` param; the **server** applies its own default cap and returns one page. You can't override it client-side without explicitly paginating. Despite the name, `NonPaginatedResponse` is NOT "all rows in one shot."
-> - `getAll({ pageSize: 200 })` → `PaginatedResponse` → API returns up to 200, plus `hasNextPage` / `nextCursor`.
+Types (`PaginationOptions`, `PaginationCursor`, `PaginatedResponse`, `NonPaginatedResponse`) and per-method pagination examples: `dist/core/index.d.ts` + each service's own `dist/<subpath>/index.d.ts` JSDoc. This file covers only server behavior and skill patterns neither documents.
+
+> **Foot-gun: every "list" call returns ONE page, even when you pass no pagination options.** `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. all make exactly one HTTP call.
 >
-> **There is no "give me everything" call.** To list every row from a source that may have more than the cap, you MUST loop the cursor:
+> - `getAll()` (no options) → SDK sends no `pageSize` param; the **server** applies its own default cap and returns one page, wrapped in a misleadingly-named `NonPaginatedResponse`. It is NOT "all rows in one shot," and you can't override the cap client-side without explicitly paginating.
+> - **There is no "give me everything" call.** To list every row from a source that may exceed the cap, loop the cursor:
 >
 > ```typescript
 > const all: T[] = [];
@@ -22,65 +22,7 @@
 >
 > **Dashboard widgets:** don't hand-write this loop in `fnBody` — the dashboard scaffold ships a typed helper: `const { fetchAll } = await import('@/lib/paginate')` then `const items = await fetchAll(cursor => svc.getAll({ pageSize: 200, cursor }))` and return `items.map(x => ({ ...x }))` (project SDK rows into `Row` objects).
 
-## Imports
-
-Import pagination types from `@uipath/uipath-typescript/core`:
-
-```typescript
-import type {
-  PaginationCursor,
-  PaginationOptions,
-  PaginatedResponse,
-  NonPaginatedResponse,
-} from '@uipath/uipath-typescript/core';
-```
-
-- `PaginationCursor`: `{ value: string }` — an opaque cursor object. Pass it to `cursor` in pagination options.
-- `PaginationOptions`: `{ pageSize?, cursor?, jumpToPage? }` (cursor and jumpToPage are mutually exclusive)
-- `PaginatedResponse<T>`: `{ items, hasNextPage, nextCursor?, previousCursor?, totalCount?, currentPage?, totalPages?, supportsPageJump }`
-- `NonPaginatedResponse<T>`: `{ items, totalCount? }`
-
-## Behavior
-
-- No pagination options passed → returns `NonPaginatedResponse<T>` (response wrapper has no pagination metadata; data is still capped at the **server's** default page limit, applied on the API side because the SDK sends no `pageSize`; see foot-gun above).
-- Any pagination option passed (pageSize, cursor, or jumpToPage) → returns `PaginatedResponse<T>` with `hasNextPage`/`nextCursor` for cursor-loop retrieval.
-
-## Cursor Navigation
-
-```typescript
-// First page
-const page1 = await service.getAll({ pageSize: 10 });
-
-// Next page using cursor
-if (page1.hasNextPage && page1.nextCursor) {
-  const page2 = await service.getAll({ cursor: page1.nextCursor });
-}
-
-// Jump to page (only for offset-based services: Assets, Queues, Tasks, Entities)
-const page5 = await service.getAll({ jumpToPage: 5, pageSize: 10 });
-```
-
-## Type Narrowing
-
-TypeScript narrows the return type at compile-time based on whether pagination options are passed. At runtime, use `'hasNextPage' in result` to discriminate — this field exists only on `PaginatedResponse`, never on `NonPaginatedResponse`.
-
-```typescript
-import type { PaginatedResponse } from '@uipath/uipath-typescript/core';
-
-// Pattern 1: When you always pass pagination options, assert the type
-const result = await tasks.getAll({ pageSize: 10 });
-// TypeScript already infers PaginatedResponse here, but if using dynamic options:
-const paginated = result as PaginatedResponse<TaskGetResponse>;
+Server behavior the types don't show:
 
-// Pattern 2: When options are dynamic and you don't know the return type
-const result = await tasks.getAll(options);
-if ('hasNextPage' in result) {
-  // PaginatedResponse — safe to access nextCursor, supportsPageJump, etc.
-  if (result.hasNextPage && result.nextCursor) {
-    const nextPage = await tasks.getAll({ cursor: result.nextCursor });
-  }
-} else {
-  // NonPaginatedResponse — only has items and totalCount
-  console.log(`All ${result.items.length} items returned`);
-}
-```
+- `jumpToPage` works only on offset-based services (Assets, Queues, Tasks, Entities) — check `supportsPageJump` on the response before offering page-jump UI.
+- Runtime discrimination when options are dynamic: `'hasNextPage' in result` — the field exists only on `PaginatedResponse`, never on `NonPaginatedResponse`.

package/skills/uipath-coded-apps/references/sdk/traces.md

@@ -1,52 +1,17 @@
 # Agent Traces (Insights RTM) Reference
 
-> Requires `@uipath/uipath-typescript` **≥ 1.4.1**. Scope: `Insights Insights.RealTimeData` (same as Agents/Agent Memory). Subpath: `@uipath/uipath-typescript/traces`.
+Signatures/params/examples: `dist/traces/index.d.ts`. Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
-Trace-level (span-level) view of agent execution — errors, latency, unit consumption, and raw spans. Distinct from the `Agents` service (`sdk/agents.md`), which aggregates per agent. Use traces when the request is about *spans*, *trace-level* timelines, or per-(agent, version, folder) unit breakdowns.
-
-```typescript
-import { AgentTraces, AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';
-const svc = new AgentTraces(sdk)
-```
-
-**Convention:** every method takes ONE optional options object — `{ startTime?: Date, endTime?: Date, folderKeys?, agentId?, agentVersion?, executionType? }`. Dates go INSIDE the object (unlike `Agents`, which uses positional Dates). Window defaults to the **last 1 year** server-side. `executionType`: `AgentTraceExecutionType.Debug | Runtime` (omit for both). Exception: the two governance methods take a **required positional `startTime: Date`** first (options second) and are GATED — full contract, gate, and module patterns in [`sdk/governance-traces.md`](governance-traces.md).
-
-The three timeline/consumption methods return a **bare array** — no `.items` / `.data` unwrapping. The span methods are listed for completeness but are record-grain (not dashboard metrics).
-
-| Method | Returns (bare array of) | Use for |
-|--------|------------------------|---------|
-| `getErrorsTimeline(options?)` | `{ name, value, date }` (`name` = error name) | Trace error volume over time |
-| `getLatencyTimeline(options?)` | `{ name, value, date }` (`value` = **seconds**) | Trace latency over time |
-| `getUnitConsumption(options?)` | `{ agentId, folderKey, agentVersion, agentUnitsConsumed, platformUnitsConsumed }` | Per-agent AGU/PLTU totals (ranked table) |
-| `getSpansByTraceId(traceId)` | `AgentSpanGetResponse[]` | All spans of one trace (drill-down, not a metric) |
-| `getSpansByReference(referenceId, options?)` | paginated `AgentSpanGetResponse` | Spans under a reference id (drill-down, not a metric) |
-| `getGovernanceDecisions(startTime, options?)` **(≥ 1.5.1, org-admin)** | paginated `.items` decision rows | Runtime-governance policy checks — see `sdk/governance-traces.md` |
-| `getGovernanceSummary(startTime, options?)` **(≥ 1.5.1, org-admin)** | single summary object | Governance posture breakdowns — see `sdk/governance-traces.md` |
-
-## getErrorsTimeline
+> The two governance methods (`getGovernanceDecisions` / `getGovernanceSummary`) are **org-admin, GATED** — full contract, gate, and module patterns in [`sdk/governance-traces.md`](governance-traces.md).
 
-```json
-[ { "name": "ToolTimeout", "value": 4, "date": "2026-06-02" },
-  { "name": "ValidationError", "value": 1, "date": "2026-06-02" } ]
-```
-
-`name` is the **error name/category** (not an agent name — contrast with `Agents.getErrorsTimeline`).
-
-## getLatencyTimeline
-
-```json
-[ { "name": "P50", "value": 0.82, "date": "2026-06-02" },
-  { "name": "P95", "value": 2.40, "date": "2026-06-02" } ]
-```
+Trace-level (span-level) view of agent execution — errors, latency, unit consumption, and raw spans. Distinct from the `Agents` service (`sdk/agents.md`), which aggregates per agent. Use traces when the request is about *spans*, *trace-level* timelines, or per-(agent, version, folder) unit breakdowns.
 
-`value` is **decimal seconds**. `name` is a series/grouping label — the exact values are not guaranteed to be `P50`/`P95`. For a robust default, average `value` per `date` into a single series; inspect live `name` values before plotting distinct series with a `multi-line-chart`.
+> **Cross-service contrast warning:** conventions and field semantics differ from `Agents` (options-object vs positional dates, `name` = error vs agent, seconds vs ms) — read each signature/JSDoc; do NOT pattern-match from `Agents` to `AgentTraces`.
 
-## getUnitConsumption
+## Traps
 
-```json
-[ { "agentId": "ag-0001", "folderKey": "f-1001", "agentVersion": "1.2.0", "agentUnitsConsumed": 340, "platformUnitsConsumed": 0 },
-  { "agentId": "ag-0002", "folderKey": "f-1001", "agentVersion": "1.0.0", "agentUnitsConsumed": 1210, "platformUnitsConsumed": 12 } ]
-```
+- `executionType`: omit to include BOTH `Debug` and `Runtime` (the option's JSDoc does not state this).
+- `getLatencyTimeline`: `name` is a series/grouping label with NO guaranteed values (unlike `Agents`, where observed values are `P50`/`P95`). For a robust default, average `value` per `date` into a single series; inspect live `name` values before plotting distinct series with a `multi-line-chart`.
 
 ## Module patterns
 
@@ -86,4 +51,4 @@ return consumption.map(x => ({ ...x }))
 
 ## Spans (drill-down only)
 
-`getSpansByTraceId(traceId)` and `getSpansByReference(referenceId, options?)` return raw span records (`AgentSpanGetResponse`: `id`, `traceId`, `parentId`, `name`, `startTime`, `endTime`, `attributes`, `status`, `spanType`, `jobKey`, `referenceId`, …). These are record-grain trace inspection, not aggregate dashboard metrics — use them for a `fetchDetail` drill-down, not a top-level widget. `getSpansByReference` is paginated (use `fetchAll`).
+`getSpansByTraceId(traceId)` and `getSpansByReference(referenceId, options?)` return raw span records — record-grain trace inspection, not aggregate dashboard metrics. Use them for a `fetchDetail` drill-down, not a top-level widget. `getSpansByReference` is paginated (use `fetchAll`).