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

package/skills/uipath-coded-apps/references/dashboards/plugins/build/impl.md

@@ -313,12 +313,14 @@ The skill ships ONE artifact — `assets/fixtures/governance-dashboard-starter-k
 
 > **Extracting the kit (the agent does this).** Before building, extract the archive into the project dir with the OS `tar` — built into Windows 10+, macOS, and Linux (one command, no per-OS variants). `<ROUTING_NAME>` is the project folder **relative to the session working directory** — never an absolute path. **Pass the archive on stdin (`-f -`), not as a path argument:**
 > ```
-> mkdir -p "<ROUTING_NAME>" && tar -xz -C "<ROUTING_NAME>" -f - < "<ARCHIVE>"
+> mkdir -p "<ROUTING_NAME>" && tar --no-same-owner --no-same-permissions -xz -C "<ROUTING_NAME>" -f - < "<ARCHIVE>"
 > ```
 > `build-dashboard.mjs` verifies the kit landed and fails loud with the exact command if not. `<ARCHIVE>` is `<SKILL_BASE_DIR>/assets/fixtures/governance-dashboard-starter-kit.tar.gz`.
 >
 > **Why stdin, not `tar -xzf "<ARCHIVE>"`:** GNU tar (the `tar` on PATH in Git Bash / MSYS on Windows) reads an archive path containing a drive colon — `C:\…` — as a remote `host:path` and dies with `tar: Cannot connect to C: resolve failed`. `--force-local` fixes GNU tar but is rejected by bsdtar (Windows `System32\tar.exe`, macOS), so it isn't portable. Feeding the archive on stdin sidesteps the colon entirely and works on GNU tar **and** bsdtar. Do not "simplify" this back to `-f "<ARCHIVE>"`.
 
+> **Why `--no-same-owner --no-same-permissions`:** entries in the kit carry whatever uid/gid and modes the packer's machine had. The archive shipped in #1591 was normalized (`0:0`, dirs `0777`); the #2323 repack was made on macOS and shipped `501:0` with dirs `0755`. Where `tar` runs with an effective uid of 0 but without full capabilities — rootless, user-namespaced CI sandboxes, which is what the eval runners use — GNU tar's default `--same-owner` chowns each directory to that foreign uid as it goes. Under `0777` the next write still succeeded; under `0755` it fails `Permission denied`. The result is a **partial** extract: top-level files and `src/lib/` land, `src/hooks/`, `src/components/`, `src/dashboard/` do not, and `tar` exits non-zero having left a half-built project behind — which the agent then abandons for a fresh `<ROUTING_NAME>`, stranding a husk that later graders cannot tell apart from the real project. Both flags work on GNU tar **and** bsdtar (macOS, Windows `System32\tar.exe`), so this stays portable. Do not drop them because a local extract works without them: an unprivileged desktop `tar` already behaves this way by default, so the failure is invisible outside CI. The durable complement is to normalize ownership at pack time in `apps-dev-tools` (`--numeric-owner --owner=0 --group=0`); these flags keep the consumer safe regardless of how the kit was packed.
+
 **Source of truth:** the scaffold + widget templates + packer live in the `apps-dev-tools` repo (`uipath-dashboard-starter-kit/`). Maintainers edit there and run `node publish.mjs` to re-pack and copy the refreshed `.tar.gz` into this skill (the version ships inside the archive at `_gen/starter-kit.json` — no separate version file). The skill is a pure consumer.
 
 ---
@@ -354,7 +356,7 @@ The build subagent prompt:
 > 2. All work happens inside the pre-warmed project folder `<ROUTING>`, which already exists in the current working directory. Reference it ONLY by this relative name — NEVER type an absolute `/tmp/…` path (a mistyped character silently builds a sibling project). Author `<ROUTING>/intent.json` (pure metadata — `schemaVersion: 2`, no `fnBody`, `"projectDir": "."`) and one `<ROUTING>/metrics/<name>.ts` per metric (`export const fetchData: MetricFn`), writing each module from the SDK references and applying the Phase 3.5 cross-check. Implement exactly this approved plan:
 >    - Project: dashboardName=`<NAME>`, routingName=`<ROUTING>`, projectDir=`"."`, orgName=`<ORG>`, tenantName=`<TENANT>`, cloudUrl=`<CLOUD_URL>`, apiUrl=`<API_URL>`, timeRange=`<RANGE>`, clientId=`<CLIENT_ID or empty>`
 >    - Widgets (one metric each): [per widget — name, tier, title, displayAs, presentation hints, and the SDK service/method it resolves to]
-> 3. Refresh the kit and build FROM INSIDE the project folder: `cd "<ROUTING>" && tar -xz -f - < "<ARCHIVE>" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" intent.json` — the `cd` fails loudly if the pre-warmed folder is missing (do NOT `mkdir` a replacement; report the failure instead), stdin-tar per § "The starter-kit archive", and the script resolves `"."` + `intent.json` against the folder you are in.
+> 3. Refresh the kit and build FROM INSIDE the project folder: `cd "<ROUTING>" && tar --no-same-owner --no-same-permissions -xz -f - < "<ARCHIVE>" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" intent.json` — the `cd` fails loudly if the pre-warmed folder is missing (do NOT `mkdir` a replacement; report the failure instead), stdin-tar per § "The starter-kit archive", and the script resolves `"."` + `intent.json` against the folder you are in.
 > 4. On `METRICS_RETRY`, fix the named `src/metrics/*.ts` files using the SDK references + the reported errors, then re-run — at most 2 attempts, then drop the metric.
 > 5. Return ONLY the milestone block defined in § "Build subagent — returns".
 
@@ -383,7 +385,7 @@ If the subagent reports `AUTH_MISSING` or a failure it couldn't recover, surface
 - Write `<ROUTING_NAME>/intent.json` — pure metadata: `schemaVersion: 2`, `dashboardName`, `routingName`, `"projectDir": "."`, `orgName`, `tenantName`, `cloudUrl`, `apiUrl`, `timeRange`, `clientId`, and a `metrics` array of metadata entries (NO `fnBody`).
 - Write one `<ROUTING_NAME>/metrics/<name>.ts` per metric — `export const fetchData: MetricFn = async (sdk) => { … }` written from the SDK references; import time windows from `@/lib/time` and `fetchAll` from `@/lib/paginate`; read-only methods only. Cross-check each against its documented example response (§ "Phase 3.5"). For a chart record-grain drill-down, also export `fetchDetail` and set `"detail": true`. For a **table row-click** drill-down, set `rowLink: { key: "<rowField>" }` on the metric and export `fetchDetailByKey(sdk, key, getToken)` (the clicked row's `<rowField>` arrives as `key`). For a KPI with a change badge, return `[{ value, previous }]` (two windows).
 
-**Step B — Refresh the kit, then run the build script once, from INSIDE the project folder.** `cd "<ROUTING_NAME>"` (fails loudly if the pre-warmed folder is missing — never `mkdir` a replacement), refresh the kit with the OS `tar` on stdin (`tar -xz -f - < "<ARCHIVE>"`; § "The starter-kit archive"), then run `node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" intent.json`. Most events are silent — translate the rest to milestones for the return block.
+**Step B — Refresh the kit, then run the build script once, from INSIDE the project folder.** `cd "<ROUTING_NAME>"` (fails loudly if the pre-warmed folder is missing — never `mkdir` a replacement), refresh the kit with the OS `tar` on stdin (`tar --no-same-owner --no-same-permissions -xz -f - < "<ARCHIVE>"`; § "The starter-kit archive"), then run `node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" intent.json`. Most events are silent — translate the rest to milestones for the return block.
 
 **Silent (never report):** `PREWARM_START`, `PREWARM_DONE`, `SCAFFOLD_READY`, `ENV_WRITTEN`, `PARTIAL_BUILD_DETECTED`.
 

package/skills/uipath-coded-apps/references/dashboards/plugins/deploy/impl.md

@@ -364,6 +364,7 @@ Always: "To update after making changes, say 'deploy this dashboard' again."
 | Publish 5xx / HTML | Wait 10s and retry (up to 4 times) |
 | Deploy "indexing" / "not been published" (with NO `--version` passed) | Propagation delay — show retry ticker, wait 10s, retry up to 3 times |
 | Deploy "not been published" but you passed `--version` | Remove `--version` from the deploy call — deploy resolves the latest version itself |
+| Deploy "not found among folders accessible to your account" | Folder propagation lag on a just-created folder, or a session missing `OR.Default` — see [pack-publish-deploy.md](../../../pack-publish-deploy.md#a-freshly-created-folder-is-not-immediately-deployable). Retry the **same** key; do not create another folder or chase it as permissions |
 | Deploy "routing name must be unique" on an upgrade | You passed `--path-name` on an upgrade — omit it; routing already exists |
 | Deploy path-name conflict (fresh deploy) | Generate new suffix, retry deploy only (pack/publish already done) |
 | "Agentic Governance is a preview feature and is not enabled for your organization" (on a pinned/governance deploy) | Not a deploy failure — the app IS deployed and reachable at its URL. Governance pinning is preview-gated: the pin just won't surface in the Governance section until the org is enrolled. Report success with the URL, add the preview note (Step 11), and tell the user to contact their UiPath representative for preview access. Do NOT retry or bump the version. |

package/skills/uipath-coded-apps/references/oauth-client-setup.md

@@ -96,6 +96,8 @@ A missing scope name (`scope not found` / `Not all scopes=<list> are present in
 
 ## Manual portal fallback
 
+> **Portal picker labels vs scope names.** In the portal, scopes are grouped under **resource labels** that differ from the CLI scope names. Pick the scopes per resource from [oauth-scopes.md](oauth-scopes.md). Some services require more than one resource.
+
 ### Create a new External Application
 
 1. Go to `https://{cloudHost}/{orgName}/portal_/admin/external-apps/oauth`

package/skills/uipath-coded-apps/references/pack-publish-deploy.md

@@ -260,6 +260,23 @@ If the exact name is ambiguous (multiple exact matches) or not found, surface an
 
 Each folder JSON object includes: `Key` (GUID — pass this to `--folder-key`), `Name`, `Path`, `Type` (`Personal` / `Solution` / `Standard`), `ParentKey`.
 
+#### A freshly created folder is not immediately deployable
+
+`uip or folders create` returns `Data.Key` as soon as the folder exists, but `deploy` validates that key against a folder lookup that lags creation by **one to three minutes**. Deploying too soon fails with a misleading error naming a key that is perfectly valid:
+
+```
+"Instructions": "Folder key '<GUID>' was not found among folders accessible to
+your account. Re-check the key with 'uip or folders list --output json'."
+```
+
+**This is propagation lag, not a bad key, and not a permissions problem.** `Retry: RetryWillNotFix` in that payload is wrong for this case — retrying the *same* key does fix it.
+
+- **Retry the same key on a backoff**, ~30s apart for up to about five minutes.
+- **Do not create another folder or switch keys.** A new folder restarts the same wait, and the retry budget resets with it.
+- **Do not chase it as permissions** — `--permission-model`, `uip or users assign`, and role grants do not affect this lookup and cost minutes.
+- **Do not re-`publish` between attempts.** Publishing again to work around a folder error yields `Package not found` on the next deploy.
+- **Prefer an existing folder when the scenario allows it.** An already-propagated folder (a resolved `Shared`, `AdminDashboards`, …) deploys immediately; only a folder created in this same session carries the lag.
+
 #### Storing the resolved key
 
 ```bash
@@ -360,6 +377,7 @@ uip codedapp deploy -n my-webapp --folder-key "$FOLDER_KEY"
 | `App not found` on deploy | App genuinely not published | Run `uip codedapp publish` first |
 | `has not been published yet` / `still being indexed` right after a successful publish | Catalog **indexing lag** — not a missing package | CLI auto-retries ~15s (1/2/4/8s backoff). If it still fails, **wait a few seconds and rerun `deploy`**. If you passed `-v <version>`, drop it — deploy defaults to Latest. |
 | `Folder key required` / deploy hangs on prompt | Missing folder key | Resolve via `uip or folders list --output json`, then run `uip codedapp deploy --folder-key <key> ...` (or `UIPATH_FOLDER_KEY=<key>` env-var prefix). |
+| `Folder key '<GUID>' was not found among folders accessible to your account` | Two causes, told apart by whether `uip or folders list` returns rows. **Rows returned:** propagation lag on a just-created folder. **Zero rows** (with `Result: Success`): session scope is missing `OR.Default` | Lag → [A freshly created folder is not immediately deployable](#a-freshly-created-folder-is-not-immediately-deployable). Scope → [debug.md](debug.md). |
 | `Missing tenant name` on publish | `UIPATH_TENANT_NAME` not set | Set in `.env` or pass `--tenant-name` |
 | `dist/ not found` | App not built | Run `npm run build` |
 | Pack shows wrong clientId | Stale `uipath.json` | `pack` copies `uipath.json` verbatim — fix `clientId` there. |

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

@@ -87,6 +87,10 @@ A deployed coded app is auto-scoped to the folder it was deployed into: the plat
 
 > **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.
 
+> **A required positional folder has no fallback — check the signature first.** Where the folder is a required positional parameter there is nothing to omit, so the fallback never applies and leaving it out is a compile error rather than a default. `jobs.stop(jobKeys, folderId)` is the usual shape — mutating operations tend to require it, list/get calls tend not to — so read the method's own signature in `dist/<service>/index.d.ts` and take it at face value. There is no hidden no-folder overload to find, so do not go looking for one.
+>
+> When it is required, either fetch the entity and use its attached method (`job.stop()`, `task.complete()`, `instance.cancel()` take no folder, though the fetch itself may still need one), or hold the folder in module config and pass it.
+
 ## 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`.

package/skills/uipath-connector-builder/SKILL.md

@@ -23,14 +23,15 @@ Author UiPath Integration Service connectors on disk with `uip is connectors bui
 1. **Inspect before editing.** On any existing connector, run `builder inspect` first to map auth, config, activities, hooks, and triggers. Never edit blind. Never invent config keys, activity paths, or IDs — read state first (`inspect`, `activity list`, `state query`).
 2. **Validate before you finish.** Run `builder validate` at the end of every workflow and after each fix — it runs the full periodic check set and exits non-zero on failure. On failure, read the reported field, fix that one entry, re-validate. After 3 failed attempts on the same error, stop and surface the `validate` output — don't keep guessing. **Don't stop at "0 errors": read the WARNINGS too** — they flag real gaps that still ship a half-built connector (a fieldless activity, a broken SR link). Treat them as must-fix unless you can articulate why a given one is acceptable.
 3. **`auth set` owns all authentication.** It writes the config entries, `authentication.type` / `typeOauth` / `authenticationTypes`, and the token-refresh resource in one call. Define scopes here too (`--scope`, `--scope-options`, `--required-scopes`, `--preselected-scopes`) — there is no separate scope command. `init --auth oauth2|customApiKey` is inline sugar for the create-time common case; everything else goes through `auth set`. Never hand-roll auth via `state patch`.
-4. **`activity create` writes both sides in one call** — the standard-resource file AND one `element.json` entry per method. Re-running on an existing activity appends/merges. Pass `--skip-sr` (or use `auth system create`) only for system resources that need no SR file. Model `GETBYID`/`PATCH`/`PUT`/`DELETE` only for TRUE by-id endpoints — never for search. The `/{primaryKey}` path param is added automatically: ALWAYS for `GETBYID`, and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also has a `GET`/`GETBYID`); a write-only/action activity keeps its base path.
+4. **`activity create` writes both sides in one call** — the standard-resource file AND one `element.json` entry per method. Re-running on an existing activity appends/merges. Pass `--skip-sr` (or use `auth system create`) only for system resources that need no SR file. Model `GETBYID`/`PATCH`/`PUT`/`DELETE` only for TRUE by-id endpoints — never for search. The by-id `/{id}` path param is added automatically: ALWAYS for `GETBYID`, and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also has a `GET`/`GETBYID`); a write-only/action activity keeps its base path. **The by-id path token and the primary key are separate** — the token is substituted before the request leaves us (the vendor never sees its name), while the primary key names a field read back from the vendor's response. A trailing `{token}` in `--vendor-path` is NOT adopted as the key; pass `--primary-key <vendor response key>`.
 5. **`state patch` REPLACES the whole node at a pointer (no merge).** To change one field: `state query` the entry, edit it, then `state patch` the COMPLETE object back. `element-metadata.json` has no addressable sub-paths — round-trip the whole file. Activity paths in pointers are URL-encoded: `/contacts` → `%2Fcontacts`. Use the dedicated authoring verbs for creation, not `state patch`.
 6. **Connector targeting.** Builder verbs walk up from the cwd, then scan immediate subdirectories, then fall back to the `.uip-connector.json` marker `init` writes in the directory it ran from — so follow-up commands from that same directory hit the last-init connector automatically, even next to other connector dirs. Pass `--connector-dir <PATH>` to override or when working from elsewhere. `import` reads `--connector-dir` the same way (the connector root holding `app/element/element.json`); on `download` it instead names the OUTPUT directory to write the pulled connector into. **Exception — `init` does NOT scan subdirectories** (it would otherwise resolve a SIBLING connector and silently EDIT/rename it): to CREATE, run `init` from a fresh/empty directory (a dir that merely *contains* connector subdirs — e.g. `/tmp` — creates a new connector, it will not dive into a child to edit it); to EDIT, run from inside the connector or pass `--connector-dir`.
 7. **Output is the `{Result, Code, Data}` envelope.** Add `--output json` to parse it. Failures exit non-zero. Never suppress stderr.
 8. **`import` / `download` / `publish` — and `init` when CREATING — need `uip login`.** Authenticate before any tenant pull/push. A NEW connector's key `design-{org}-{slug}` takes its org from your logged-in session, so `init` create ERRORS when you're not logged in. Let it derive the org; do NOT pass a guessed `--organization` (a wrong org bakes into the key and only surfaces, mismatched, at import/publish) — `--organization <slug>` is only for offline/CI builds with a known org.
 9. **Never echo, log, or hard-code a secret.** Secret config keys (client secret, API key, password, token) are written by `auth set` ENCRYPTED (`encrypt: true`) — most as `PASSWORD` fields, though some (OAuth tokens, a service-account JSON) are encrypted `TEXTFIELD`/`TEXTAREA`. End users supply real credentials at connection time; the connector holds only the auth TYPE + endpoint URLs + scopes. Use placeholders in every example command.
 10. **Prefer a built-in over a hook.** Before writing JS, consult the decision table ([references/hooks.md](references/hooks.md) §"Decide first: hook or built-in?") — a hook is only for transforms, orchestration, or derivation no declarative feature expresses. One hook file per activity+method+phase; hooks run in Denali (modern JS + `require('axios')` for secondary calls) and must end every path with `done()`.
-11. **Author the field schema for EVERY activity — `activity create` does NOT infer fields.** An activity with no fields renders in Studio Web as a single raw JSON body in and raw JSON out, with zero typed inputs/outputs — a half-built connector that still validates and publishes, so the omission is easy to miss (it's a recurring failure: "got it valid and published" while skipping the schema). After `activity create`, ALWAYS define the request/response fields from the vendor's documented schema — either pass `--fields-file <json>` on `activity create` for the whole schema at once, or add them one at a time with `activity field create`. `validate` emits a WARNING for any fieldless activity — treat it as must-fix. Never report a connector "done" with fieldless activities; if a raw-body passthrough is genuinely intended, say so explicitly.
+11. **Windows + Git Bash: disable MSYS path conversion FIRST.** In Git Bash any argument starting with `/` is rewritten to a Windows path before the CLI ever sees it — `--vendor-path /latest` lands in `element.json` as `C:/Program Files/Git/latest`, `validate` PASSES it, the connector publishes, and it only fails at request time against the vendor with no local trace. Export `MSYS_NO_PATHCONV=1` and `MSYS2_ARG_CONV_EXCL='*'` once per shell (or prefix every builder command). Affects every path option — `--vendor-path`, `--resource-path`, `--method-vendor-path`, `--reference-path`, `--validation-vendor-path`, `--path`, `--polling-url`. Quoting does NOT help (the rewrite happens after the shell strips quotes). If a connector already carries a mangled path, repair it with `state patch`.
+12. **Author the field schema for EVERY activity — `activity create` does NOT infer fields.** An activity with no fields renders in Studio Web as a single raw JSON body in and raw JSON out, with zero typed inputs/outputs — a half-built connector that still validates and publishes, so the omission is easy to miss (it's a recurring failure: "got it valid and published" while skipping the schema). After `activity create`, ALWAYS define the request/response fields from the vendor's documented schema — either pass `--fields-file <json>` on `activity create` for the whole schema at once, or add them one at a time with `activity field create`. `validate` emits a WARNING for any fieldless activity — treat it as must-fix. Never report a connector "done" with fieldless activities; if a raw-body passthrough is genuinely intended, say so explicitly.
 
 ## Connection design (host, region, discovered values)
 
@@ -73,7 +74,7 @@ uip is connectors builder init --name 'Acme Widgets' \
 uip is connectors builder activity create --name accounts --vendor-path /v1/accounts \
   --methods GET,GETBYID,POST,PATCH,DELETE --primary-key id --has-ceql
 
-# 3. Author the field schema — REQUIRED, not optional (Rule 11). `activity create`
+# 3. Author the field schema — REQUIRED, not optional (Rule 12). `activity create`
 #    does NOT infer fields; without this the activity ships as a raw JSON body and
 #    `validate` warns. Pass `--fields-file <json>` on `activity create` for the whole
 #    schema at once, or add fields one at a time with `field create`
@@ -185,10 +186,11 @@ Depth lives in `references/` — each self-contained. SKILL.md owns the workflow
 2. Hand-rolling auth via `state patch` instead of `auth set` (Rule 3) — leaves the auth block inconsistent.
 3. Editing a config entry with a partial value (Rule 5) — `state patch` REPLACES the node, dropping omitted fields. Query the whole entry and patch the complete object back.
 4. Re-running `activity create` with a name that already exists when you meant a SEPARATE activity — it's an idempotent upsert that MERGES into the same-named activity (appends methods, preserves existing field definitions unless `--overwrite-fields`); it does not error, so a wrong name silently merges instead of warning.
-5. Modeling `GETBYID` for a search/list endpoint (Rule 4) — by-id verbs auto-add the `/{primaryKey}` param; reserve them for true single-record reads.
+5. Modeling `GETBYID` for a search/list endpoint (Rule 4) — by-id verbs auto-add the `/{id}` param; reserve them for true single-record reads.
 6. Putting a real secret in an example or expecting the connector to store one (Rule 9) — secrets are encrypted fields (usually PASSWORD) supplied at connection time.
 7. Re-publishing without bumping the version — the server rejects an equal version; bump `latestVersion` or pass `--version`.
 8. Invented `--categories` values — they must come from the approved enum; `validate` reports the list.
 9. Writing a hook for a job a built-in does (Rule 10; hooks.md §"Recognizing an avoidable hook"), or omitting the trailing `done()` so the hook never returns.
 10. Reaching for a removed command — there is no `connector scaffold/inspect/validate` wrapper (use `init`/`inspect`/`validate` directly), no `global`/`metadata`/`config`/`resource*`/`event polling add`/`auth scope`/`remote*`/`describe`/`reference`.
-11. Reporting a connector "done" with fieldless activities (Rule 11) — `activity create` writes endpoints/methods/auth but NOT the field schema; an activity with no `field create` / `--fields-file` shows only a raw JSON body in Studio and trips a `validate` WARNING. Author fields before finishing, and never treat a 0-error/has-warnings validate as a pass.
+11. Naming a field — especially the primary key — after a URL path token or your own convention instead of the key the vendor actually returns. Response fields are resolved by name against the raw vendor JSON, so a wrong name yields an empty activity output and NO error at any layer (standard-resources.md §fields).
+12. Reporting a connector "done" with fieldless activities (Rule 12) — `activity create` writes endpoints/methods/auth but NOT the field schema; an activity with no `field create` / `--fields-file` shows only a raw JSON body in Studio and trips a `validate` WARNING. Author fields before finishing, and never treat a 0-error/has-warnings validate as a pass.

package/skills/uipath-connector-builder/references/debugging.md

@@ -43,8 +43,12 @@ exits non-zero on failure). All run under `uip is connectors builder`.
   so it matches the element.json resource path. See [standard-resources.md](standard-resources.md).
 - **Methods aren't curated activities**: a method created with `--no-curate` has no `curated`
   block — re-run `activity create` (curates by default) or `activity method curate`.
-- **by-id confusion**: GETBYID/PATCH/DELETE auto-add the `/{primaryKey}` path param; only
+- **by-id confusion**: GETBYID/PATCH/DELETE auto-add the `/{id}` path param; only
   model GETBYID for TRUE by-id endpoints, not search.
+- **an output field is always empty at run time**: its `name` doesn't match a key the vendor
+  returns. Response fields are resolved by name (dot-path) against the raw vendor JSON, and a
+  miss binds to an empty output with no error — check the real payload and rename the field
+  (a primary key inherited from a URL token is the classic case).
 
 ## Hook issues
 - **done() not called**: an exception or a branch skips `done()`.

package/skills/uipath-connector-builder/references/element-json.md

@@ -50,8 +50,10 @@ GET/GETBYID/POST/PATCH/DELETE has 5 entries (one `activity create` call writes t
 | `expressions` | no | `requestBodyRoot` / `responseBodyRoot` for JSON-path wrap/unwrap. |
 
 For by-id methods (`GETBYID`/`PATCH`/`PUT`/`DELETE`) `activity create` auto-adds the
-`/{primaryKey}` path param — ALWAYS for `GETBYID`, and for the write methods only on a CRUD
+`/{id}` path param — ALWAYS for `GETBYID`, and for the write methods only on a CRUD
 activity (one that also has `GET`/`GETBYID`); a write-only activity keeps its base path.
+The token names a URL slot only; it is not the primary key and is never read back from the
+vendor response.
 Details in [standard-resources.md](standard-resources.md) §"by-id methods".
 
 ### Resource types

package/skills/uipath-connector-builder/references/standard-resources.md

@@ -49,14 +49,33 @@ activity's fields also need field-level `requestCurated`/`responseCurated` visib
 see **fields** below.
 
 ### by-id methods (GETBYID / PATCH / PUT / DELETE)
-`activity create` auto-adds the `/{primaryKey}` path param for by-id methods, so a
-GETBYID method's path becomes `/<object>/{id}` without extra flags. The suffix is added
-ALWAYS for `GETBYID`, and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also
-defines `GET`/`GETBYID`); a write-only activity keeps its base path. A per-method
+`activity create` auto-adds an `/{id}` path param for by-id methods, so a GETBYID method's
+path becomes `/<object>/{id}` without extra flags. The suffix is added ALWAYS for `GETBYID`,
+and for `PATCH`/`PUT`/`DELETE` only when the activity is CRUD (it also defines
+`GET`/`GETBYID`); a write-only activity keeps its base path. A per-method
 `--method-vendor-path GETBYID=/foo` override that lacks `{id}` STILL works — the id param
 is derived from the canonical resource path. Only model GETBYID for TRUE by-id endpoints,
 not a search/list-by-filter endpoint.
 
+**The path token and the primary key are different things — never derive one from the
+other.** The token in `/meetings/{meetingId}` is substituted before the request leaves the
+platform: the vendor only ever sees `/meetings/1234`, so the token's NAME is arbitrary and
+says nothing about the response. `metadata.primaryKey` names a **response field**, which is
+resolved by name against the vendor's raw JSON (see "fields" below). If you pass
+`--vendor-path /latest/{base_currency}` the CLI keeps `{base_currency}` as the path token
+and defaults the primary key to `id` — it will NOT adopt `base_currency` as the key, and it
+warns so you set the real one. Declare the key the vendor actually returns:
+
+```bash
+# vendor returns {"base_code":"USD", …} but the URL slot is {base_currency}
+uip is connectors builder activity create --name rates \
+  --vendor-path '/latest/{base_currency}' --methods GETBYID --primary-key base_code
+```
+
+Catalogue connectors do exactly this — HubSpot Marketing `get_contact_list` has
+`metadata.primaryKey: ["listId"]` (a real response key) while its GETBYID path is
+`/lists/{list_id}`, with `list_id` existing only as an input parameter.
+
 ### nested / parent-id vendor paths (mid-path `{token}`)
 A path variable is bound on TWO sides: element-side `{name}` in the internal `path`, vendor-side
 `{vendorName}` in the `vendorPath`. When a `{token}` sits **only in the vendor path** — a
@@ -84,8 +103,20 @@ internal path, and a `{token}` in the vendorPath with no param sending it (unbou
 [events.md](events.md) §"SR-level event metadata".
 
 ## fields — definitions (top-level object)
-Each key = field name and MUST equal `field.name`. Add/update with `activity field
-create --resource <name> --name <field> [--type <t>]`. Re-running MERGES: top-level keys
+Each key = field name and MUST equal `field.name`.
+
+**`field.name` must be the key the vendor actually returns.** There is no field-level
+response mapping — no `vendorPath`, `vendorName`, or transformation exists on an SR field,
+and element-service does not project the response through the field list at all (it returns
+the vendor body, minus an optional `rootKey` unwrap). The activity runtime resolves each
+declared field by looking `field.name` up as a **dot-path into the raw vendor JSON**
+(`owner_id.name`, `email[*].value` — nesting and arrays are expressed in the name itself,
+as shipped connectors like Pipedrive do). Matching is exact and case-sensitive. A field
+whose name the vendor never sends binds to an **empty activity output with no error
+anywhere** — so a guessed name is indistinguishable from a working one until run time.
+Author fields from the vendor's documented response, not from the URL or your own naming.
+
+Add/update with `activity field create --resource <name> --name <field> [--type <t>]`. Re-running MERGES: top-level keys
 you pass win, unspecified keys are kept, and per-method visibility is deep-merged.
 `--type` is required only for a NEW field, optional on a merge.