@salesforce/afv-skills 1.17.0 → 1.19.0

package/skills/syncing-test-providers/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: syncing-test-providers
+description: "Re-syncs a configured DevOps Center test provider on a pipeline to pick up new test suites, via the Connect API sync endpoint, after explicit user confirmation. Takes a pipelineId and one or more testProviderIds and triggers an asynchronous re-sync so newly added suites become available for assignment. Use this skill when a test provider (e.g. Apex Unit Tests, Code Analyzer, Flow Tests, Provar) has had suites added since it was last configured and the user wants those suites to show up in DevOps Center. TRIGGER when: the user wants to re-sync a test provider, pull in new suites from a provider, refresh a provider's suite list, or says assigned suites are missing/out of date for a configured provider. DO NOT TRIGGER when: configuring a provider for the first time (that creates a new DevopsPipelineTestProvider configuration), or assigning/mapping existing suites to a stage (use managing-suite-assignments)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Syncing Test Providers
+
+Re-syncs a configured test provider on a DevOps Center pipeline so that suites added to the provider since it was last configured become available for assignment to stages.
+
+**Confirmation required:** Yes — explicit confirmation before the sync is triggered.
+
+## Prerequisites
+
+Load `checking-devops-prerequisites` first — Prerequisites 1–4 (org login, Agentforce DX plugin, DevOps Center org auth, pipeline identified). Prerequisite 5 (stage) is **not** required: providers are synced at the pipeline level, not the stage level.
+
+| Variable | Source |
+|---|---|
+| `doce-org-alias` | Established in Prerequisite 1 |
+| `pipelineId` | Identified in Prerequisite 4 (pipeline selection) |
+| `testProviderId` | Resolved by fetching the pipeline's test providers (below) |
+
+---
+
+## Step 1 — Fetch test providers to resolve the provider ID
+
+Get all test providers configured on the pipeline so you can resolve the `testProviderId` and confirm the provider name with the user:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/testProviders?status=all" \
+  --target-org <doce-org-alias>
+```
+
+Each provider entry includes `testProviderId`, `testProviderName`, and a status (Configured vs. Available). Present a short summary grouped by status:
+
+```text
+Test providers for <pipelineName>:
+
+✓ Configured:
+- Code Analyzer (63 suites)
+- Apex Unit Tests (5 suites)
+
+Available (not yet configured):
+- Flow Tests
+```
+
+- **Only a Configured provider can be synced.** If the user names an *Available* (not-yet-configured) provider, explain it must be configured first — this skill does not configure providers.
+- If the pipeline has no configured providers, report that and stop — do NOT fabricate a provider or ID.
+
+## Step 2 — Confirmation gate
+
+**Required — do not call the API before the user confirms.**
+
+> "I'll re-sync `<testProviderName>` on the `<pipelineName>` pipeline to pick up any new suites. Confirm?"
+
+Do not proceed until the user gives an affirmative response.
+
+## Step 3 — Trigger the sync
+
+On confirmation, call the sync endpoint with the provider ID(s) and pipeline ID:
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/sync" \
+  --method POST \
+  --body '{
+    "testProviderIds": ["<testProviderId>"],
+    "pipelineId": "<pipelineId>"
+  }' \
+  --target-org <doce-org-alias>
+```
+
+`testProviderIds` is a list — multiple configured providers can be synced in one call.
+
+## On success
+
+> "Provider `<testProviderName>` sync started. The operation is running asynchronously — new suites will be available shortly."
+
+The sync runs asynchronously; newly synced suites can then be assigned to stages with `managing-suite-assignments`.
+
+---
+
+## Critical gotcha
+
+**Do NOT use** `POST /connect/devops/pipeline/<pipelineId>/testProvider` to sync — that endpoint **creates a new provider configuration** and will result in duplicate `DevopsPipelineTestProvider` records. Sync only via `POST /connect/devops/sync`.
+
+## Error Handling
+
+Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages:
+
+| Status | User-facing message |
+|---|---|
+| 400 | "The sync request was invalid. Check that the provider ID and pipeline ID are correct." |
+| 403 | "You don't have permission to sync test providers on this pipeline." |
+| 404 | "The pipeline or test provider was not found." |
+| 500 | "A server error occurred. Try again in a few minutes." |
+
+---
+
+## Related skills
+
+- **`checking-devops-prerequisites`** — loaded first to establish org and pipeline context.
+- **`configuring-test-provider`** — use to configure an available provider for the first time; this skill only re-syncs already-configured providers.
+- **`managing-suite-assignments`** — after a sync surfaces new suites, use this to assign or map them to a pipeline stage.
+- **`recommending-devops-tests`** — to recommend which of the newly synced suites to run.

package/skills/using-salesforce-archive/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: using-salesforce-archive
+description: "ALWAYS USE THIS SKILL for anything involving Salesforce Archive (also called Trusted Services Archive) — search, view, unarchive, analyze, mask, and erase (RTBF) archived records via the Archive Connect API, and reading archive job status from the ArchiveActivity object. TRIGGER when: user mentions Salesforce Archive, Trusted Services Archive, archive/unarchive records, ArchiveActivity, archive jobs, archive policy, archive analyzer, archived record search, archive storage, archive failure logs, right to be forgotten / RTBF on archived data, or masking archived PII — including phrasings like 'find records that were archived', 'restore archived data', 'why did the archive job fail', 'download the archive failure log', or 'monitor my archive jobs', AND even when they ask you to explain, give guidance, or write a runbook/doc about these topics rather than run code. SKIP when: the user wants generic data-export/backup unrelated to the Archive add-on, or wants to build the archive policy UI metadata."
+metadata:
+  version: "1.0"
+---
+
+# Salesforce Archive
+
+Operate Salesforce Archive (also called Trusted Services Archive) through its Connect API and the `ArchiveActivity` job-metadata object. This skill covers how to search and restore archived records, run the analyzer, handle RTBF erasure and PII masking, check storage, and — the part most often missed — how to read archive job status from `ArchiveActivity` and use a job's Id + Type to download its logs.
+
+## Scope
+
+- **In scope**: Calling the Archive Connect API operations under `/platform/data-resilience/archive/`; querying the `ArchiveActivity` object via SOQL/Connect; correlating a job's `ArchiveActivity` record with its log-download endpoints; the verify-after-write pattern for each async operation.
+- **Out of scope**: Defining archive policies / `ArchivePolicyDefinition` metadata; building UI; generating Flows over archive data (`ArchiveActivity` is **not** Flow-queryable — see Gotchas); generic backup/export tooling unrelated to the add-on.
+
+---
+
+## Required Inputs
+
+Gather or infer before acting:
+
+- **Operation intent**: search, view, 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.
+- 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.
+
+| 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` |
+| `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
+
+All steps are sequential within a task. Read the referenced file the first time you touch that area.
+
+1. **Identify the operation and read the contract** — do not rely on general knowledge of the Archive API, which has non-obvious contracts. Load `references/connect-api-operations.md` for the exact request/response shape, required inputs, and per-operation gotchas of every Archive Connect API operation. Do this before constructing any call (e.g. `dateRanges` plural vs singular, `isSuccess` flag vs HTTP status, `url: null` meaning no log).
+
+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.
+
+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.
+
+5. **Verify after every write** — re-read state to confirm the effect (see the Verify-After-Write table below). Async operations (analyzer, RTBF, masking) return a request id you must poll.
+
+---
+
+## Verify-After-Write
+
+| After this write | Confirm by |
+|------------------|-----------|
+| `run-analyzer` | Poll `get-analyzer-report` until the report is populated |
+| `unarchive-records` | Re-run `search-archived-records` — confirm records left the archive |
+| `forget-archived-records` (RTBF) | Poll `get-rtbf-status` with the returned `request_id` |
+| `mask-archived-records` | Poll `get-masking-status` with the returned `request_id` |
+
+---
+
+## Rules / Constraints
+
+| 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. |
+| 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." |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| 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"`. |
+| 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. |
+| Hitting unarchive caps | Unarchive processes ≤1000 matched records per request and ≤50 requests/hour/org, and restores the whole archived hierarchy of each match. |
+| RTBF/masking caps | `criteria` ≤10 entries (one per object); ≤10,000 root records/day (shared between RTBF and masking); masking is irreversible. Both RTBF and masking are gated by the same `Rtbf` user permission. |
+
+---
+
+## Output Expectations
+
+This is a knowledge/API skill — it produces API calls and their interpreted results, plus SOQL against `ArchiveActivity`. It does not generate deployable metadata. Deliverables per task: the correct operation invocation(s), the right success-signal branching, and a verify-after-write confirmation.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/connect-api-operations.md` | Before constructing any Archive Connect API call — full per-operation contracts, success signals, and limits |
+| `references/archive-activity-entity.md` | For any job-status / failure / progress / log task — `ArchiveActivity` field reference and its link to the log-download endpoints |
+| `examples/monitor-failed-jobs.md` | To follow an end-to-end monitoring flow: find failed/in-progress jobs, then download their logs |

package/skills/using-salesforce-archive/examples/monitor-failed-jobs.md

@@ -0,0 +1,47 @@
+# Example — Monitor failed archive jobs and download their logs
+
+End-to-end flow for the most common archive-admin task: find the jobs that failed or stalled, read why, and pull the logs that show which records didn't make it.
+
+## 1. Find the jobs (query ArchiveActivity)
+
+`ArchiveActivity` is not Flow-queryable, so use SOQL/Connect:
+
+```sql
+SELECT Id, Name, Status, Type, StartTime, ProgressPercentage,
+       TotalRecordCount, SucceededCount, FailedCount, SkippedRootRecordsCount,
+       RootEntityName, FailureReason
+FROM ArchiveActivity
+WHERE (Status = 'Failed' OR Status = 'In Progress' OR Status = 'Ended With Errors')
+  AND StartTime >= LAST_N_DAYS:7
+ORDER BY StartTime DESC
+```
+
+Read each row's `ProgressPercentage`, `SucceededCount`/`FailedCount`, `RootEntityName`, and `FailureReason` to summarize health. In-progress jobs have a blank `EndTime`.
+
+## 2. For each failed job, get the logs
+
+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:**
+```
+GET /platform/data-resilience/archive/log/execution-details-stream-url
+    ?requestId={activity.Id}&reportType={activity.Type}
+```
+
+**Failed-records log:**
+```
+GET /platform/data-resilience/archive/log/failed-records-stream-url
+    ?requestId={activity.Id}&reportType={activity.Type}
+```
+
+Each returns `{ url }`. **Check `url != null`** before using it — a `null` url means no log was resolved for that job/type (e.g. the job produced no failed-records file), not an error to retry blindly.
+
+## 3. Summarize
+
+Per failed/in-progress job, report: Name, Status, ProgressPercentage, SucceededCount, FailedCount, RootEntityName (target object), FailureReason, and the two log URLs (or "no log available" when `url` is null).
+
+## Pitfalls this flow avoids
+
+- **Not** attempting a Flow over `ArchiveActivity` (`isProcessEnabled=false` → "You can't get ArchiveActivity records in a flow").
+- Passing the activity's real `Type` as `reportType` (a mismatch returns no log).
+- Treating a 201 with `url: null` as a usable log.

package/skills/using-salesforce-archive/references/archive-activity-entity.md

@@ -0,0 +1,59 @@
+# ArchiveActivity — Data Model Reference
+
+`ArchiveActivity` is the platform entity that records **job metadata for Salesforce Archive jobs** (archive, purge, analyze, unarchive, export). Every archive job produces one `ArchiveActivity` record; you read it to learn a job's status, progress, and outcome, and you use its `Id` + `Type` to download the job's logs.
+
+## Entity facts
+
+| Property | Value |
+|----------|-------|
+| API name | `ArchiveActivity` |
+| 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 |
+| 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. |
+
+## Fields
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `Name` | Auto-number | `ARCV-…` job identifier |
+| `Status` | enum `ArchiveActivityStatus` | Lifecycle: scheduled, running / **In Progress**, completed, **Failed**, canceled, **Ended With Errors** |
+| `Type` | enum `ArchiveActivityType` | The job mode: Archive, Purge, Analyze(r), Unarchive, Export-to-external-bucket, Export-and-download. **This is the `reportType` for log downloads.** |
+| `StartTime` | DateTime | When execution began |
+| `EndTime` | DateTime | When execution finished/terminated (blank while running) |
+| `ArchivePolicyDefinition` | Lookup (FK) | Parent `ArchivePolicyDefinition`; child relationship `ArchiveActivities` |
+| `RootEntityName` | Text | API name of the target sObject being archived |
+| `TotalRecordCount` | Long | Records initially selected (succeeded + failed + skipped) |
+| `AttemptedRootRecordsCount` | Long (formula) | `SkippedRootRecordsCount + FailedCount + SucceededCount` — top-level records actually attempted |
+| `SkippedRootRecordsCount` | Long | Top-level records skipped (validation, exclusion filters, data-protection thresholds) |
+| `SucceededCount` | Long | Records processed without error |
+| `FailedCount` | Long | Records that failed (validation, missing refs, exceptions) |
+| `ProgressPercentage` | Double | Percent complete |
+| `FailureReason` | Long text | Why the job failed/partially completed (system error messages or policy-level failures) |
+| `RecordsSizeInMb` | Text | Estimated total size of processed records (MB) |
+
+> The entity also defines a `ProgressIcon` display formula for list views; it is not useful for programmatic monitoring — read `Status`, `ProgressPercentage`, and the count fields directly.
+
+## How ArchiveActivity links to the Connect API
+
+The log-download endpoints (`get-execution-details-stream-url`, `get-failed-records-stream-url`) take:
+
+- `requestId` = an `ArchiveActivity` **`Id`** (`8qv…`) of a completed, log-producing job, and
+- `reportType` = that same activity's **`Type`** value.
+
+So the monitoring pattern is: **query `ArchiveActivity` → pick the job(s) of interest → pass each job's `Id` and `Type` to the stream-url operation → check `url != null`.** See `../examples/monitor-failed-jobs.md`.
+
+## Example SOQL
+
+```sql
+-- Failed or in-progress jobs in the last 7 days, newest first
+SELECT Id, Name, Status, Type, StartTime, EndTime, ProgressPercentage,
+       TotalRecordCount, SucceededCount, FailedCount, SkippedRootRecordsCount,
+       RootEntityName, FailureReason, ArchivePolicyDefinitionId
+FROM ArchiveActivity
+WHERE (Status = 'Failed' OR Status = 'In Progress' OR Status = 'Ended With Errors')
+  AND StartTime >= LAST_N_DAYS:7
+ORDER BY StartTime DESC
+```

package/skills/using-salesforce-archive/references/connect-api-operations.md

@@ -0,0 +1,157 @@
+# 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.
+
+## Operations Summary
+
+| Operation | Purpose | Method + Path | Verify with |
+|-----------|---------|---------------|-------------|
+| `search-archived-records` | read | `POST /search` | — |
+| `search-archived-records-with-sharing-rules` | read (Agentforce) | `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` | — |
+| `unarchive-records` | write | `POST /unarchive` | re-run `search-archived-records` |
+| `forget-archived-records` (RTBF) | write | `POST /rtbf` | `get-rtbf-status` |
+| `get-rtbf-status` | read | `GET /rtbf/{requestId}` | — |
+| `mask-archived-records` | write | `POST /mask` | `get-masking-status` |
+| `get-masking-status` | read | `GET /mask/{requestId}` | — |
+| `get-execution-details-stream-url` | read | `GET /log/execution-details-stream-url` | — |
+| `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
+graph TD
+  run_analyzer["run-analyzer"] -.verify.-> get_analyzer_report["get-analyzer-report"]
+  forget_archived_records["forget-archived-records"] -.verify.-> get_rtbf_status["get-rtbf-status"]
+  mask_archived_records["mask-archived-records"] -.verify.-> get_masking_status["get-masking-status"]
+  unarchive_records["unarchive-records"] -.verify.-> search_archived_records["search-archived-records"]
+```
+
+---
+
+## search-archived-records (`POST /search`)
+
+Search archived records by object, filters, date ranges, and sort.
+
+**Required**: `sobjectName` + at least 1 filter. Missing them returns a clean envelope validation error (`statusCode 400`).
+
+**Inputs**:
+- `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.
+- `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`.
+
+**Excluded objects**: `Feed`, `History`, `Relation`, `Share` are not searchable; Files/Attachments are not retrievable.
+
+### Pagination
+
+Read records inline from each response. If `body.scroll_id != "-1"`, call `get-search-archived-records-next-page` with that `scroll_id`. **STOP when `scroll_id == "-1"`** — calling next-page with `"-1"` (the terminal sentinel) → 500. There is no separate fetch-by-requestId step.
+
+## get-search-archived-records-next-page (`GET /search/next/{scrollId}`)
+
+**Input**: `scrollId` *(string, path param)* — the `body.scroll_id` from a prior search. Stop when it is `"-1"`; never call with `"-1"`.
+**Output**: `body` (next page), `errorMessage`, `statusCode` — same envelope as search.
+
+---
+
+## 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`).
+
+**Required**: `objectName`, `filtersJson`.
+
+**Inputs**:
+- `objectName` *(string)* — API name of the sObject.
+- `filtersJson` *(string)* — JSON-encoded **OBJECT MAP** of `fieldName → value`, e.g. `"{\"Subject\":\"Foo\",\"Status\":\"New\"}"`. **NOT** an array of `{field,value}` objects — the array form is rejected with `isSuccess:false "No valid filters provided. Please provide filtersJson"`.
+- `dateField` *(string)* — API name of the date field for temporal filtering.
+- `startDate` / `endDate` *(string)* — search window bounds (ISO-8601).
+- `maxResults` *(integer)* — max records to return; default 100.
+
+**Output**: `isSuccess` *(boolean — **branch on THIS, not the HTTP status**)*, `totalResultCount`, `records` (rich-text summary of ~5 key fields per record), `recordsJson` (HTML-entity-encoded JSON string), `errorMessage`, `message`, `warnings` (schema-validation/auto-fix advisories). **Validation failures surface as HTTP 201 + `isSuccess:false` + `errorMessage`, never a 4xx.** Pattern: `isSuccess:false` + `errorMessage` → caller bug; `isSuccess:true` + `recordsJson` → success.
+
+---
+
+## 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.
+
+`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"`).
+
+---
+
+## unarchive-records (`POST /unarchive`)
+
+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.
+
+**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).
+
+**Output**: `body` (unarchive job details incl. job id), `errorMessage`, `statusCode`. **Verify** by re-running `search-archived-records`. **Rollback**: re-archive via a new archive job with the same criteria.
+
+---
+
+## forget-archived-records / RTBF (`POST /rtbf`) + get-rtbf-status (`GET /rtbf/{requestId}`)
+
+Submits a Right-To-Be-Forgotten erasure request.
+
+**Input**: `criteria` *(array of `{sobject, field, value}`)* — ≤10 items, **one per object type**; ≤10,000 root records erased per org/day; field/object names case-insensitive. Deletes the **entire archived hierarchy** of each match (no partial deletion). Note: the criterion must match a record archived **as a root** — filtering a parent (e.g. Account by Id) when only its children were archived matches nothing.
+
+**Output**: HTTP 201, `body.request_id` *(UUID)*. Poll `get-rtbf-status` (path param `requestId` = that UUID) → `body.status` (e.g. `"Request is open. Scan is still in progress"`). **Rollback**: none — RTBF erasure is permanent.
+
+---
+
+## mask-archived-records (`POST /mask`) + get-masking-status (`GET /mask/{requestId}`)
+
+Submits a PII-masking (anonymization) request — irreversibly replaces detected PII values with placeholders (e.g. `redacted@example.com`) while keeping the record + non-PII fields searchable.
+
+**Input**: `criteria` *(array of `{sobject, field, value}`)* — same shape as RTBF.
+
+**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.
+
+**Output**: HTTP 201, `body.request_id` *(UUID)*. Poll `get-masking-status` (path param `requestId`); status reaches **HANDLED** when complete. **Rollback**: none — anonymization is permanent.
+
+---
+
+## Log Downloads — get-execution-details-stream-url / get-failed-records-stream-url
+
+Both are `GET /log/...` and mint a one-time presigned download URL. `get-execution-details-stream-url` → the execution-detail log; `get-failed-records-stream-url` → the failed-records log (records that did not process). Identical contract.
+
+**Output**: `{ url }`. **`url != null` is success; `url: null` means no log was resolved** (missing/incorrect `requestId`/`reportType`, or the activity produced no such log) — always check `url != null`; never treat `url:null` or the 201 status alone as success.
+
+**Required inputs**:
+- `requestId` *(string)* — the **`ArchiveActivity` Id** (`8qv…` key) of a completed, log-producing job present in the archiver backend — **not** a search requestId. A missing/non-matching id → `url:null`.
+- `reportType` *(string)* — that activity's `Type`: `Archive | Unarchive | Analyzer | Purge | Export-to-external-bucket | Export-and-download`. Omitting it → `url:null`.
+- `sobjectName` *(string, optional)* — the backend self-resolves it.
+
+This is the bridge between `ArchiveActivity` (see `archive-activity-entity.md`) and downloadable logs.
+
+---
+
+## get-archive-storage-used (`GET /storage/archive-used`)
+
+Returns `body.usedStorage[4]` (doubles — per-tier bytes consumed) and `body.availableStorage[4]` (per-tier capacity) — two **parallel positional arrays** (NOT a flat metric, NOT key/value maps). The 4 slots are the same in both:
+
+| Index | Meaning |
+|-------|---------|
+| 0 | Salesforce org **DATA** storage |
+| 1 | Salesforce org **FILE** storage |
+| 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.