@salesforce/afv-skills 1.24.0 → 1.25.0

package/skills/platform-trust-archive-manage/SKILL.md

@@ -20,33 +20,31 @@ Operate Salesforce Archive (also called Trusted Services Archive) through its Co
 
 Gather or infer before acting:
 
-- **Operation intent**: search, view, unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
+- **Operation intent**: search (this is also how you view archived records), unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
 - **Target sObject** (`sobjectName`): required for search and unarchive.
 - **Filters**: search and unarchive require `sobjectName` + at least one filter.
 - **For log downloads**: the `requestId` (an `ArchiveActivity` Id, `8qv…` prefix) of a completed, log-producing job, and `reportType` = that activity's `Type`.
 
 Preconditions (confirm or surface to the user if a call returns a not-permitted error):
-- The **org** must have Salesforce Archive enabled (the `TrustedServicesArchive` / `TrustedServicesArchiveBt` org permission). Every operation is gated on this first.
+- The **org** must have Salesforce Archive enabled. Every operation is gated on this first.
 - Each operation requires a **specific user permission** on top of the org gate — see the Permissions table below. There is no single "archive admin" role; access is per-capability.
 
 ---
 
 ## Permissions
 
-Every operation first requires the org to have Salesforce Archive enabled (`hasTrustedServicesArchive` = `OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt`). On top of that org gate, each capability is gated by a distinct **user permission**. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.
+Every operation first requires the org to have Salesforce Archive enabled. On top of that org gate, each capability is gated by a distinct **user permission**. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.
 
 | Operation | User permission required |
 |-----------|--------------------------|
-| `search-archived-records`, `get-search-archived-records-next-page` | `ViewSearchPage` (Archive Search) — the Connect search endpoint runs the global-search path, gated by Archive Search, **not** `ViewArchivedRecords` |
-| `search-archived-records-with-sharing-rules` (Agentforce) | `ViewArchivedRecords` |
+| `search-archived-records`, `get-search-archived-records-next-page` | `ViewSearchPage` (Archive Search) — **not** `ViewArchivedRecords` |
+| `search-archived-records-with-sharing-rules` | `ViewArchivedRecords` |
 | `unarchive-records` | `UnarchiveSdk` |
 | `forget-archived-records` (RTBF) + `get-rtbf-status` | `Rtbf` |
 | `mask-archived-records` + `get-masking-status` | `Rtbf` (masking shares the same `Rtbf` permission — **not** a separate entitlement) |
 | `run-analyzer`, `get-analyzer-report`, `get-archive-storage-used` | `ArchiveAnalyzer` |
 | `get-execution-details-stream-url`, `get-failed-records-stream-url` | `ViewActivitiesPage` (Archive Activities) |
 
-> Source of truth: the Connect API resource classes in `trusted-services-archive-connect-impl` → `TrustedServicesArchiveSdkImpl` guards → `TrustedServicesArchive.accessChecks.xml`. Note `search-archived-records` routes through `performArchiverGlobalSearch` (gated by `canRunArchiveSearch` = `ViewSearchPage`); the separate Apex-SDK `searchArchivedRecords()` method is gated by `ViewArchivedRecords`, but the **Connect API** search endpoint does not use it.
-
 ---
 
 ## Workflow
@@ -57,7 +55,24 @@ All steps are sequential within a task. Read the referenced file the first time
 
 2. **For job status / monitoring, read the data model** — when the task involves archive jobs, failures, progress, counts, or logs, load `references/archive-activity-entity.md` for the `ArchiveActivity` field reference and how it links to the Connect API. Query `ArchiveActivity` via SOQL or Connect — **not** Flow. For a worked end-to-end example (find failed/in-progress jobs, then pull their execution-detail and failed-records logs), load `examples/monitor-failed-jobs.md`.
 
-3. **Construct and send the call** — follow the contract exactly. For searches, supply `sobjectName` + ≥1 filter; for date filtering use the plural `dateRanges` array of `{field, from, to}` with full ISO-8601 datetimes.
+3. **Construct and send the call** — every operation is a `{method, path, body}` REST call. Send it with whatever Connect/REST API tool your environment provides (an MCP server that invokes Connect/REST APIs, the `sf` CLI, or any REST client). Two path rules are critical (full per-operation contracts are in `references/connect-api-operations.md`):
+
+   - **The operation names in this skill are NOT URL paths.** `search-archived-records`, `unarchive-records`, etc. are labels; never put them in the path. Use the short literal paths below (each relative to base `/platform/data-resilience/archive`). Sending the operation name as a path segment (e.g. `/…/archive/search-archived-records`) returns **404**.
+   - **The path stops at `/platform/data-resilience/archive/…` — there is NO `/connect` segment**, even though this is a Connect API. A **404 / `NOT_FOUND` here means the path is wrong, NOT that Archive is disabled** — fix the path before concluding the add-on is missing.
+
+   | Operation | Method + Path | Notes |
+   |-----------|---------------|-------|
+   | search-archived-records | `POST /search` | requires `sobjectName` + ≥1 filter |
+   | search next page | `GET /search/next/{scrollId}` | stop when `scroll_id == "-1"` |
+   | search with sharing rules | `POST /search/with-sharing-rules` | uses `filtersJson` object map |
+   | unarchive-records | `POST /unarchive` | `sobjectName` + filters |
+   | run-analyzer / report | `POST /analyzer/run` · `GET /analyzer/report` | |
+   | forget / RTBF + status | `POST /rtbf` · `GET /rtbf/{requestId}` | |
+   | mask + status | `POST /mask` · `GET /mask/{requestId}` | |
+   | storage used | `GET /storage/archive-used` | |
+   | execution-detail / failed-records log | `GET /log/execution-details-stream-url` · `GET /log/failed-records-stream-url` | query params `requestId`, `reportType` |
+
+   With the `sf` CLI, prefix the path with `/services/data/v67.0`; some MCP/REST tools take the bare path and add the version themselves (tool-dependent — see the reference). Then follow the contract: for searches, supply `sobjectName` + ≥1 filter; for date filtering use the plural `dateRanges` array of `{field, from, to}` with full ISO-8601 datetimes.
 
 4. **Branch on the right signal** — some operations return HTTP 201 with a body-level success flag (`body.statusCode`, `body.isSuccess`). Read `references/connect-api-operations.md` for which signal to trust per operation; never assume the HTTP status alone means success.
 
@@ -80,12 +95,11 @@ All steps are sequential within a task. Read the referenced file the first time
 
 | Constraint | Rationale |
 |-----------|-----------|
-| Search & unarchive require `sobjectName` + at least one filter | The controller rejects an unfiltered request with "Search must be based on at least 1 field" — a full-object operation is never allowed. |
+| Search & unarchive require `sobjectName` + at least one filter | An unfiltered request is rejected with "Search must be based on at least 1 field" — a full-object operation is never allowed. |
 | Date filters must be full ISO-8601 datetimes (`2020-01-01T00:00:00Z`) | A date-only value (`2020-01-01`) returns `400 JSON_PARSER_ERROR` because the field is typed `xsd:dateTime`. |
 | Search uses `dateRanges` (plural array); unarchive uses `dateRange` (singular) | They are genuinely different fields on the two endpoints; using the wrong shape silently drops the filter or 400s. |
 | Stop pagination when `scroll_id == "-1"` | Calling `get-search-archived-records-next-page` with `"-1"` returns 500. |
 | Log downloads need a real `ArchiveActivity` Id as `requestId` + that activity's `Type` as `reportType` | The backend resolves the log by the activity record; a mismatched `reportType` returns no log. |
-| Never use the deprecated lookups | `global-search-by-id`, `get-global-search-results`, and `view-archived-records` are deprecated with no successor and currently 500. Use `search-archived-records` (+ next-page) instead. |
 | Excluded objects are not retrievable | `Feed`, `History`, `Relation`, `Share` are not searchable; Files/Attachments are not retrievable via this API — do not promise them. |
 | Query `ArchiveActivity` via SOQL/Connect, never Flow | `ArchiveActivity` has `isProcessEnabled=false`, so a Flow "Get Records" element on it fails with "You can't get ArchiveActivity records in a flow." |
 
@@ -97,7 +111,7 @@ All steps are sequential within a task. Read the referenced file the first time
 |-------|------------|
 | Treating HTTP 201 as success | Several operations return 201 with a body-level outcome. Branch on `body.statusCode` (search) or `body.isSuccess` (`with-sharing-rules`), not the HTTP code. |
 | `run-analyzer.isRunning` used as a signal | It is **always** `null`; the endpoint only populates `message`. Poll `get-analyzer-report` to confirm completion instead. |
-| `search-archived-records-with-sharing-rules` (Agentforce) filters as an array | `filtersJson` must be a JSON-encoded **object map** `{"Field":"Value"}`, not an array of `{field,value}`; the array form returns `isSuccess:false "No valid filters provided"`. |
+| `search-archived-records-with-sharing-rules` filters as an array | `filtersJson` must be a JSON-encoded **object map** `{"Field":"Value"}`, not an array of `{field,value}`; the array form returns `isSuccess:false "No valid filters provided"`. |
 | Log `url` treated as present because status is 201 | `get-*-stream-url` returns `{url}`; `url: null` means no log was resolved. Always check `url != null`. |
 | Misreading `get-archive-storage-used` | `usedStorage[]`/`availableStorage[]` are parallel positional arrays: index 0=org DATA, 1=org FILE, 2=archive RECORDS, 3=archive FILE. `availableStorage[2]`/`[3]` are **always 0** (archive tier is unmetered) — that means "not tracked", not "full". |
 | Expecting `ArchiveActivity` in a Flow | It is not Flow-enabled (`isProcessEnabled=false`). Use SOQL/Connect/Reports. |

package/skills/platform-trust-archive-manage/examples/monitor-failed-jobs.md

@@ -23,13 +23,13 @@ Read each row's `ProgressPercentage`, `SucceededCount`/`FailedCount`, `RootEntit
 Take the job's `Id` (`8qv…`) as `requestId` and its `Type` as `reportType`. `{activity.Type}` below is a placeholder for that job's own `Type` field value (e.g. `Archive`, `Purge`, `Unarchive`, `Analyzer`) — substitute the actual value per job; a hardcoded/mismatched `reportType` returns no log.
 
 **Execution-detail log:**
-```
+```text
 GET /platform/data-resilience/archive/log/execution-details-stream-url
     ?requestId={activity.Id}&reportType={activity.Type}
 ```
 
 **Failed-records log:**
-```
+```text
 GET /platform/data-resilience/archive/log/failed-records-stream-url
     ?requestId={activity.Id}&reportType={activity.Type}
 ```

package/skills/platform-trust-archive-manage/references/archive-activity-entity.md

@@ -10,7 +10,7 @@
 | Key prefix | `8qv` (record Ids start `8qv…`) |
 | Owning product | Salesforce Archive (Trusted Services Archive) |
 | Kind | **Standard platform entity** (not a custom object) |
-| License gate | Requires the Trusted Services Archive add-on (`TrustedServicesArchive.hasTrustedServicesArchive`) — absent on orgs without the add-on |
+| License gate | Requires the Trusted Services Archive add-on — absent on orgs without the add-on |
 | Name field | Auto-number, mask `ARCV-{0000000000}` |
 | Flow-enabled? | **No** — `isProcessEnabled=false`. A Flow "Get Records" element on it fails: "You can't get ArchiveActivity records in a flow." Query via SOQL / Connect / Reports. |
 

package/skills/platform-trust-archive-manage/references/connect-api-operations.md

@@ -1,13 +1,54 @@
 # Salesforce Archive Connect API — Operations Reference
 
-All operations are under the base path `/platform/data-resilience/archive/`. Contracts verified live against archived data. Read the operation you need before constructing the call — several contracts are non-obvious.
+Read the operation you need before constructing the call — several contracts are non-obvious.
+
+## How to call these operations
+
+Every operation is a REST call defined by three things:
+
+- **method** — `GET` or `POST` (see the `Method + Path` column below)
+- **path** — the resource path, e.g. `/platform/data-resilience/archive/search`
+- **body** — a JSON object (POST only); GET operations carry their inputs as query-string params and send no body
+
+```text
+{method} /platform/data-resilience/archive/{operation-path}
+```
+
+The `/platform/...` path *is* the complete resource path — there is **no `/connect` segment** and you do not append the operation name (details below). Use API version `67.0`.
+
+**Send it with whatever Connect/REST API tool your environment provides** — an MCP server that invokes Connect/REST APIs, the `sf` CLI, or any REST client. Map the three primitives above to that tool's parameters.
+
+**Whether the path needs the `/services/data/v67.0` prefix depends on the tool, not on MCP-vs-CLI** — some tools want the full versioned URL, others take the bare `/platform/...` path and add the version/host themselves. Check the tool's own docs; if a bare path returns `NOT_FOUND`, try the full versioned form (and vice-versa).
+
+**If using the `sf` CLI** — supply the **full versioned URL** and pass the body inline. The `--body` flag takes the JSON itself, **not** a filename (a bare filename is sent verbatim → `JSON_PARSER_ERROR`):
+
+```bash
+sf api request rest "/services/data/v67.0/platform/data-resilience/archive/search" \
+  --method POST \
+  --body '{"sobjectName":"Account","filters":[{"field":"Name","value":"salesforce.com"}],"fields":["Id","Name","Phone"]}' \
+  --target-org <org-alias>
+```
+
+**If using an MCP server / other REST client** — map method, path, and body to its parameters (names vary per tool; check its docs). For example, the body for the same search is:
+
+```text
+{"sobjectName":"Account","filters":[{"field":"Name","value":"salesforce.com"}],"fields":["Id","Name","Phone"]}
+```
+
+(For GET operations, append the inputs as query-string params on the path and send no body.)
+
+> Two path rules that otherwise surface as a misleading error, **regardless of how you send the call**:
+> - **Use the literal path from the `Method + Path` column below — never build one from the operation name.** The operation identifiers in this doc (`search-archived-records`, `unarchive-records`, …) are *names*, not URL segments. The real path is short and rarely matches the name: `searchArchivedRecords` → `POST /search` (NOT `/search-archived-records`), `unarchiveRecords` → `POST /unarchive`, `getArchiveStorageUsed` → `GET /storage/archive-used`. Synthesizing the path from the operation name (e.g. kebab-casing it and appending it) produces a route that returns **404** even though the operation exists. Always copy the path string verbatim from the table.
+> - **The path stops at `/platform/data-resilience/archive/...`** — there is no `/connect` segment, even though this is a Connect API. Inserting one returns `NOT_FOUND` for the whole namespace, which can read as "Archive is disabled" — it isn't; it's the path.
 
 ## Operations Summary
 
-| Operation | Purpose | Method + Path | Verify with |
+The first column is the **operation name** used to refer to each op in this skill — it is **not** part of the path. The method and path to send are in the **Method + Path** column; each path shown (e.g. `POST /search`) is shorthand for `POST /platform/data-resilience/archive/search`.
+
+| Operation (name only — NOT a path segment) | Purpose | Method + Path (send THIS) | Verify with |
 |-----------|---------|---------------|-------------|
 | `search-archived-records` | read | `POST /search` | — |
-| `search-archived-records-with-sharing-rules` | read (Agentforce) | `POST /search/with-sharing-rules` | — |
+| `search-archived-records-with-sharing-rules` | read | `POST /search/with-sharing-rules` | — |
 | `get-search-archived-records-next-page` | read | `GET /search/next/{scrollId}` | — |
 | `run-analyzer` | write | `POST /analyzer/run` | `get-analyzer-report` |
 | `get-analyzer-report` | read | `GET /analyzer/report` | — |
@@ -20,8 +61,6 @@ All operations are under the base path `/platform/data-resilience/archive/`. Con
 | `get-failed-records-stream-url` | read | `GET /log/failed-records-stream-url` | — |
 | `get-archive-storage-used` | read | `GET /storage/archive-used` | — |
 
-**Deprecated — do not use** (no successor; currently 500): `global-search-by-id`, `get-global-search-results`, `view-archived-records`. Use `search-archived-records` (+ `get-search-archived-records-next-page`) for all archived-record lookups.
-
 ### Verify-after-write dependencies
 
 ```mermaid
@@ -44,12 +83,12 @@ Search archived records by object, filters, date ranges, and sort.
 - `sobjectName` *(string)* — API name of the sObject to search.
 - `filters` *(array)* — Filter conditions, each `{field, value}` where **both are required strings**. `value` is a single string — **not** an array, **not** nullable (null/omitted → `400 "This field may not be null"`). There is **no `operator` field**. **At least 1, up to 6 filters, combined with AND only** (OR is not supported). Example: `[{"field":"Subject","value":"Foo"}]`.
 - `dateRanges` *(array)* — Primary date filter: array of `{field, from, to}`. `from`/`to` must be full ISO-8601 datetime (`"2020-01-01T00:00:00Z"`); date-only → `400 JSON_PARSER_ERROR` (xsd:dateTime). Use the special field `archive_date` to filter by archive date instead of `CreatedDate`/`ModifiedDate`.
-- `dateRange` *(object)* — Optional **singular** convenience range `{field, from, to}`; the controller folds it into `dateRanges` (one-element equivalent). Same singular shape that `unarchive-records` uses.
+- `dateRange` *(object)* — Optional **singular** convenience range `{field, from, to}`; treated as a one-element `dateRanges`. Same singular shape that `unarchive-records` uses.
 - `fields` *(array)* — Field API names to return.
 - `pageSize` *(integer)* — Records per page; default 25, max 1000.
 - `sortDirection` *(string)* — `asc`/`desc`, case-insensitive, default `asc`; an invalid value → 400.
 
-**Output**: HTTP **201**, `body = { records[], total_result_count, scroll_id }`, `body.statusCode = 200`, `errorMessage` null on success. **Branch on `body.statusCode`, not the HTTP code** — once past framework validation the response is always 200/201 even on logical failure, with the error in `errorMessage` + `statusCode`.
+**Output**: HTTP **201**, `body = { records[], total_result_count, scroll_id }`, `body.statusCode = 200`, `errorMessage` null on success. **Branch on `body.statusCode`, not the HTTP code** — once past request validation the response is always 200/201 even on logical failure, with the error in `errorMessage` + `statusCode`.
 
 **Excluded objects**: `Feed`, `History`, `Relation`, `Share` are not searchable; Files/Attachments are not retrievable.
 
@@ -66,7 +105,7 @@ Read records inline from each response. If `body.scroll_id != "-1"`, call `get-s
 
 ## search-archived-records-with-sharing-rules (`POST /search/with-sharing-rules`)
 
-Archive search **optimized for Agentforce agents**. (There is no `/search/related` endpoint — this is the operation that takes the JSON filter map.) Gated by the **`ViewArchivedRecords`** user permission (unlike plain `search-archived-records`, which uses `ViewSearchPage`).
+Archive search that enforces the user's sharing rules. (There is no `/search/related` endpoint — this is the operation that takes the JSON filter map.) Gated by the **`ViewArchivedRecords`** user permission (unlike plain `search-archived-records`, which uses `ViewSearchPage`).
 
 **Required**: `objectName`, `filtersJson`.
 
@@ -83,7 +122,7 @@ Archive search **optimized for Agentforce agents**. (There is no `/search/relate
 
 ## run-analyzer (`POST /analyzer/run`) + get-analyzer-report (`GET /analyzer/report`)
 
-`run-analyzer` triggers the analyzer; HTTP 201, output `message` *(string, human-readable status)*. **`isRunning` is ALWAYS `null`** — the controller only populates `message`; never branch on `isRunning`. Poll `get-analyzer-report` to confirm completion. Non-destructive / idempotent.
+`run-analyzer` triggers the analyzer; HTTP 201, output `message` *(string, human-readable status)*. **`isRunning` is ALWAYS `null`** — only `message` is populated; never branch on `isRunning`. Poll `get-analyzer-report` to confirm completion. Non-destructive / idempotent.
 
 `get-analyzer-report` returns `body` with: `topRecords[]` (`{objectName, objectLabel, objectIcon, size, count, usagePercent}` per archivable sObject), `topFiles[]` (parallel shape for files), `fileGeneralStorage`/`dataGeneralStorage` (`{storageUsed, storageRemaining, usagePercent}`), and `createdDateReport` (`"DD/MM/YYYY HH:MM:SS"`).
 
@@ -96,7 +135,7 @@ Restore archived records back into live storage by criteria.
 **Inputs**:
 - `sobjectName` *(string)* — sObject whose records to unarchive.
 - `filters` *(array)* — criteria identifying which archived records to restore.
-- `dateRange` *(object)* — optional **SINGULAR** range `{field, from, to}` (reads `getDateRange()`, unlike `/search` which uses plural `dateRanges`); full ISO-8601 datetimes. Omit to unarchive by filters alone.
+- `dateRange` *(object)* — optional **SINGULAR** range `{field, from, to}` (unlike `/search`, which uses the plural `dateRanges`); full ISO-8601 datetimes. Omit to unarchive by filters alone.
 
 **Caps**: ≤1000 matched records (else not processed); ≤50 unarchive requests/hour/org. Restores the **whole archived hierarchy** of each match. Requires the **`UnarchiveSdk`** user permission (on top of org-level Archive enablement).
 
@@ -122,7 +161,7 @@ Submits a PII-masking (anonymization) request — irreversibly replaces detected
 
 **Behavior**: permanent; one-time per record (re-requests on an already-masked record are ignored); shares the 10,000/day RTBF rate limit; **PII fields are auto-detected** (you cannot choose them); records under legal hold / retention lock are excluded; cascades to child records. Available **only via this API** (not in the Archive UI).
 
-**Permission**: gated by the **`Rtbf`** user permission — the SAME permission as RTBF (`maskArchivedRecords` runs the RTBF access check), not a separate masking entitlement.
+**Permission**: gated by the **`Rtbf`** user permission — the SAME permission as RTBF, not a separate masking entitlement.
 
 **Output**: HTTP 201, `body.request_id` *(UUID)*. Poll `get-masking-status` (path param `requestId`); status reaches **HANDLED** when complete. **Rollback**: none — anonymization is permanent.
 
@@ -154,4 +193,4 @@ Returns `body.usedStorage[4]` (doubles — per-tier bytes consumed) and `body.av
 | 2 | Archive-tier **RECORDS** storage |
 | 3 | Archive-tier **FILE** storage |
 
-**`availableStorage[2]` and `[3]` (the archive tier) are ALWAYS 0**: the controller hardcodes them (`ARCHIVER_AVAILABLE_STORAGE = 0`) because archive storage is unmetered, so a `0` there means "not tracked", NOT "no space left". Only `availableStorage[0]`/`[1]` (live org data/file remaining) are real. All values rounded to 2 decimals.
+**`availableStorage[2]` and `[3]` (the archive tier) are ALWAYS 0**: archive storage is unmetered, so a `0` there means "not tracked", NOT "no space left". Only `availableStorage[0]`/`[1]` (live org data/file remaining) are real. All values rounded to 2 decimals.