@salesforce/afv-skills 1.17.0 → 1.18.0

package/skills/running-code-analyzer/scripts/list-rules.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Version: v1.0 | SHA256: placeholder
+// List Code Analyzer rules matching a selector and return structured JSON
+// Usage: node list-rules.js <selector> [options]
+//
+// This script runs `sf code-analyzer rules --rule-selector <selector>` and
+// parses the table output into structured JSON for presentation.
+//
+// The CLI table format is:
+//   #   Name                   Engine   Severity       Tags
+//   1   @lwc/lwc/no-inner-html eslint   2 (High)       Recommended, LWC, Security
+//
+// Output: JSON with {status, totalRules, rules: [{name, engine, severity, severityNum, tags}], engines, summary}
+
+const { execSync } = require("child_process");
+
+function printUsage() {
+  console.error(`Usage: node list-rules.js <selector> [options]
+
+Arguments:
+  <selector>           Rule selector (same syntax as --rule-selector)
+                       Examples: "Security", "pmd", "eslint:Recommended",
+                       "(pmd,eslint):Security:(1,2)", "Apex", "JavaScript"
+
+Options:
+  --engine <name>      Filter results to a specific engine after listing
+  --severity <n>       Filter results to specific severity (1-5, comma-separated)
+  --top <n>            Return at most N rules (default: 100)
+  --count-only         Return only counts by engine/severity/category (no rule list)
+
+Valid selector tokens:
+  Engines: eslint, regex, retire-js, flow, pmd, cpd, sfge
+  Severities: Critical/1, High/2, Moderate/3, Low/4, Info/5
+  Categories: Security, Performance, BestPractices, CodeStyle, Design, ErrorProne, Documentation
+  Languages: Apex, JavaScript, TypeScript, HTML, CSS, Visualforce, XML
+  Tags: Recommended, Custom, All, DevPreview, LWC, Fixable
+
+Examples:
+  node list-rules.js "Security"
+  node list-rules.js "pmd:Security"
+  node list-rules.js "eslint:Recommended"
+  node list-rules.js "(pmd,eslint):Security:(1,2)"
+  node list-rules.js "Apex"
+  node list-rules.js "JavaScript:BestPractices"
+  node list-rules.js "Recommended" --count-only
+  node list-rules.js "all" --engine pmd --severity 1,2 --top 10`);
+  process.exit(1);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const selector = args[0];
+const options = {
+  engine: null,
+  severity: null,
+  top: 100,
+  countOnly: false,
+};
+
+for (let i = 1; i < args.length; i++) {
+  switch (args[i]) {
+    case "--engine":
+      options.engine = (args[++i] || "").toLowerCase();
+      break;
+    case "--severity":
+      options.severity = (args[++i] || "")
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => n >= 1 && n <= 5);
+      break;
+    case "--top":
+      options.top = parseInt(args[++i] || "25", 10);
+      break;
+    case "--count-only":
+      options.countOnly = true;
+      break;
+    default:
+      console.error(`Unknown option: ${args[i]}`);
+      printUsage();
+  }
+}
+
+// Validate selector tokens before running CLI
+const validationError = validateSelector(selector);
+if (validationError) {
+  console.log(JSON.stringify({
+    status: "invalid_selector",
+    message: validationError,
+    hint: "Valid tokens: engines (pmd, eslint, cpd, retire-js, regex, flow, sfge), severities (1-5 or Critical/High/Moderate/Low/Info), categories (Security, Performance, BestPractices, CodeStyle, Design, ErrorProne, Documentation), languages (Apex, JavaScript, TypeScript, HTML, CSS, Visualforce, XML), tags (Recommended, Custom, All, DevPreview, LWC, Fixable)",
+  }));
+  process.exit(0);
+}
+
+// Run `sf code-analyzer rules`
+let rawOutput;
+try {
+  const cmd = `sf code-analyzer rules --rule-selector "${selector}" 2>&1`;
+  rawOutput = execSync(cmd, {
+    encoding: "utf8",
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+} catch (err) {
+  rawOutput = err.stdout || err.stderr || (err.output && err.output.join("")) || "";
+  if (!rawOutput) {
+    console.log(JSON.stringify({
+      status: "error",
+      message: `Failed to run sf code-analyzer rules: ${err.message}`,
+    }));
+    process.exit(0);
+  }
+}
+
+// Parse the table output
+const rules = parseTableOutput(rawOutput);
+
+if (rules.length === 0) {
+  console.log(JSON.stringify({
+    status: "no_rules_found",
+    message: `No rules matched selector "${selector}". Check the selector syntax or try a broader query.`,
+    hint: "Use tokens like: Security, pmd, eslint:Recommended, (1,2), Apex",
+  }));
+  process.exit(0);
+}
+
+// Apply post-filters
+let filtered = rules;
+if (options.engine) {
+  filtered = filtered.filter((r) => r.engine.toLowerCase() === options.engine);
+}
+if (options.severity) {
+  filtered = filtered.filter((r) => options.severity.includes(r.severityNum));
+}
+
+// Compute summary stats
+const engineCounts = {};
+const severityCounts = {};
+const categoryCounts = {};
+filtered.forEach((r) => {
+  engineCounts[r.engine] = (engineCounts[r.engine] || 0) + 1;
+  const sevKey = `${r.severityNum} (${severityName(r.severityNum)})`;
+  severityCounts[sevKey] = (severityCounts[sevKey] || 0) + 1;
+  (r.tags || []).forEach((tag) => {
+    const t = tag.trim();
+    if (["Security", "Performance", "BestPractices", "CodeStyle", "Design", "ErrorProne", "Documentation"].includes(t)) {
+      categoryCounts[t] = (categoryCounts[t] || 0) + 1;
+    }
+  });
+});
+
+// Build result
+const result = {
+  status: "success",
+  selector,
+  totalRules: filtered.length,
+  summary: {
+    byEngine: engineCounts,
+    bySeverity: severityCounts,
+    byCategory: categoryCounts,
+  },
+};
+
+if (!options.countOnly) {
+  result.rules = filtered.slice(0, options.top).map((r) => ({
+    name: r.name,
+    engine: r.engine,
+    severity: r.severity,
+    severityNum: r.severityNum,
+    tags: r.tags,
+  }));
+  if (filtered.length > options.top) {
+    result.truncated = true;
+    result.showing = options.top;
+  }
+}
+
+console.log(JSON.stringify(result));
+
+// --- Helper Functions ---
+
+function parseTableOutput(output) {
+  const rules = [];
+  const lines = output.split("\n");
+
+  for (const line of lines) {
+    // Match table rows: starts with spaces + number
+    // Format: "  1   ruleName   engine   severity   tags"
+    const match = line.match(/^\s+(\d+)\s{2,}(\S+)\s{2,}(\S+)\s{2,}(\d+\s*\([^)]+\))\s{2,}(.+)$/);
+    if (match) {
+      const severityStr = match[4].trim();
+      const sevNumMatch = severityStr.match(/^(\d)/);
+      rules.push({
+        name: match[2].trim(),
+        engine: match[3].trim(),
+        severity: severityStr,
+        severityNum: sevNumMatch ? parseInt(sevNumMatch[1], 10) : 0,
+        tags: match[5].trim().split(",").map((t) => t.trim()).filter(Boolean),
+      });
+    }
+  }
+
+  return rules;
+}
+
+function validateSelector(selector) {
+  if (!selector || !selector.trim()) {
+    return "Selector cannot be empty.";
+  }
+
+  const VALID_TOKENS = new Set([
+    // Engines
+    "eslint", "regex", "retire-js", "flow", "pmd", "cpd", "sfge",
+    // Severity names
+    "critical", "high", "moderate", "low", "info",
+    // Severity numbers
+    "1", "2", "3", "4", "5",
+    // General tags
+    "recommended", "custom", "all",
+    // Categories
+    "bestpractices", "codestyle", "design", "documentation", "errorprone", "security", "performance",
+    // Languages
+    "apex", "css", "html", "javascript", "typescript", "visualforce", "xml",
+    // Engine-specific
+    "devpreview", "lwc", "fixable",
+  ]);
+
+  // Split by : (AND), then handle () groups (OR)
+  const groups = selector.split(":").map((s) => s.trim()).filter(Boolean);
+  const invalid = [];
+
+  for (const group of groups) {
+    let tokens;
+    if (group.startsWith("(") && group.endsWith(")")) {
+      // OR group: (token1,token2)
+      tokens = group.slice(1, -1).split(",").map((t) => t.trim()).filter(Boolean);
+    } else {
+      tokens = [group];
+    }
+
+    for (const token of tokens) {
+      if (!VALID_TOKENS.has(token.toLowerCase())) {
+        invalid.push(token);
+      }
+    }
+  }
+
+  if (invalid.length > 0) {
+    return `Invalid selector token(s): ${invalid.join(", ")}. Did you misspell a token?`;
+  }
+  return null;
+}
+
+function severityName(num) {
+  const names = { 1: "Critical", 2: "High", 3: "Moderate", 4: "Low", 5: "Info" };
+  return names[num] || "Unknown";
+}

package/skills/running-code-analyzer/scripts/query-results.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Version: v1.0 | SHA256: placeholder
+// Query and filter Code Analyzer results JSON with rich filtering capabilities
+// Usage: node query-results.js <results-file.json> [options]
+//
+// Options:
+//   --engine <name>        Filter by engine (pmd, eslint, cpd, retire-js, etc.)
+//   --severity <n>         Filter by severity (1-5, comma-separated for multiple)
+//   --category <tag>       Filter by category/tag (Security, Performance, etc.)
+//   --rule <name>          Filter by exact rule name (case-insensitive)
+//   --file <substring>     Filter by file path substring
+//   --top <n>              Return top N results (default: 10)
+//   --sort <field>         Sort by: severity, rule, engine, file (default: severity)
+//   --sort-dir <dir>       Sort direction: asc, desc (default: asc)
+//   --summary              Show only summary counts (no individual violations)
+
+const fs = require("fs");
+const path = require("path");
+
+function printUsage() {
+  console.error(`Usage: node query-results.js <results-file.json> [options]
+
+Options:
+  --engine <name>        Filter by engine (pmd, eslint, cpd, retire-js, etc.)
+  --severity <n>         Filter by severity (1-5, comma-separated for multiple: 1,2)
+  --category <tag>       Filter by category/tag (Security, Performance, BestPractices, etc.)
+  --rule <name>          Filter by exact rule name (case-insensitive)
+  --file <substring>     Filter by file path substring (case-insensitive)
+  --top <n>              Return top N results (default: 10)
+  --sort <field>         Sort by: severity, rule, engine, file (default: severity)
+  --sort-dir <dir>       Sort direction: asc, desc (default: asc)
+  --summary              Show only summary counts (no individual violations)
+
+Examples:
+  node query-results.js results.json --engine pmd --severity 1,2
+  node query-results.js results.json --category Security --top 20
+  node query-results.js results.json --file AccountService.cls
+  node query-results.js results.json --rule ApexCRUDViolation
+  node query-results.js results.json --summary`);
+  process.exit(1);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const filePath = args[0];
+const options = {
+  engine: null,
+  severity: null,
+  category: null,
+  rule: null,
+  file: null,
+  top: 10,
+  sort: "severity",
+  sortDir: "asc",
+  summary: false,
+};
+
+// Parse named options
+for (let i = 1; i < args.length; i++) {
+  const arg = args[i];
+  switch (arg) {
+    case "--engine":
+      options.engine = (args[++i] || "").toLowerCase();
+      break;
+    case "--severity":
+      options.severity = (args[++i] || "")
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => n >= 1 && n <= 5);
+      break;
+    case "--category":
+      options.category = (args[++i] || "").toLowerCase();
+      break;
+    case "--rule":
+      options.rule = (args[++i] || "").toLowerCase();
+      break;
+    case "--file":
+      options.file = (args[++i] || "").toLowerCase();
+      break;
+    case "--top":
+      options.top = parseInt(args[++i] || "10", 10);
+      break;
+    case "--sort":
+      options.sort = args[++i] || "severity";
+      break;
+    case "--sort-dir":
+      options.sortDir = args[++i] || "asc";
+      break;
+    case "--summary":
+      options.summary = true;
+      break;
+    default:
+      console.error(`Unknown option: ${arg}`);
+      printUsage();
+  }
+}
+
+// Read and parse results file
+let data;
+try {
+  data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+} catch (err) {
+  console.error(`Error reading results file: ${err.message}`);
+  process.exit(1);
+}
+
+const runDir = data.runDir || "";
+const violations = data.violations || [];
+
+// Apply filters
+let filtered = violations.filter((v) => {
+  if (options.engine && v.engine.toLowerCase() !== options.engine) return false;
+  if (options.severity && !options.severity.includes(v.severity)) return false;
+  if (options.category) {
+    const tags = (v.tags || []).map((t) => t.toLowerCase());
+    if (!tags.includes(options.category)) return false;
+  }
+  if (options.rule && v.rule.toLowerCase() !== options.rule) return false;
+  if (options.file) {
+    const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+    const fileLower = ((loc && loc.file) || "").toLowerCase();
+    if (!fileLower.includes(options.file)) return false;
+  }
+  return true;
+});
+
+// Sort
+const sortMul = options.sortDir === "desc" ? -1 : 1;
+filtered.sort((a, b) => {
+  let cmp = 0;
+  switch (options.sort) {
+    case "severity":
+      cmp = a.severity - b.severity;
+      break;
+    case "rule":
+      cmp = a.rule.localeCompare(b.rule);
+      break;
+    case "engine":
+      cmp = a.engine.localeCompare(b.engine);
+      break;
+    case "file": {
+      const aLoc = a.locations && a.locations[a.primaryLocationIndex || 0];
+      const bLoc = b.locations && b.locations[b.primaryLocationIndex || 0];
+      const aFile = (aLoc && aLoc.file) || "";
+      const bFile = (bLoc && bLoc.file) || "";
+      cmp = aFile.localeCompare(bFile);
+      break;
+    }
+  }
+  if (cmp !== 0) return cmp * sortMul;
+  // Secondary sort: severity ascending
+  return (a.severity - b.severity) * sortMul;
+});
+
+// Build output
+const totalMatches = filtered.length;
+const limited = filtered.slice(0, options.top);
+
+// Compute severity breakdown of matches
+const sevCounts = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+filtered.forEach((v) => {
+  if (sevCounts[v.severity] !== undefined) sevCounts[v.severity]++;
+});
+
+// Compute rule frequency for matches
+const ruleCounts = {};
+const ruleEngines = {};
+filtered.forEach((v) => {
+  ruleCounts[v.rule] = (ruleCounts[v.rule] || 0) + 1;
+  if (!ruleEngines[v.rule]) ruleEngines[v.rule] = v.engine;
+});
+const topRules = Object.entries(ruleCounts)
+  .sort((a, b) => b[1] - a[1])
+  .slice(0, options.top)
+  .map(([rule, count]) => ({ rule, engine: ruleEngines[rule], count }));
+
+// Compute file frequency for matches
+const fileCounts = {};
+filtered.forEach((v) => {
+  const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+  let file = (loc && loc.file) || "unknown";
+  if (runDir && file.startsWith(runDir)) file = file.substring(runDir.length + 1);
+  fileCounts[file] = (fileCounts[file] || 0) + 1;
+});
+const topFiles = Object.entries(fileCounts)
+  .sort((a, b) => b[1] - a[1])
+  .slice(0, options.top)
+  .map(([file, count]) => ({ file, count }));
+
+// Build result object
+const result = {
+  query: {
+    engine: options.engine,
+    severity: options.severity,
+    category: options.category,
+    rule: options.rule,
+    file: options.file,
+    top: options.top,
+    sort: options.sort,
+    sortDir: options.sortDir,
+  },
+  totalViolations: violations.length,
+  totalMatches,
+  severityCounts: sevCounts,
+  topRules,
+  topFiles,
+};
+
+if (!options.summary) {
+  result.violations = limited.map((v) => {
+    const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+    let file = (loc && loc.file) || "unknown";
+    if (runDir && file.startsWith(runDir)) file = file.substring(runDir.length + 1);
+    return {
+      rule: v.rule,
+      engine: v.engine,
+      severity: v.severity,
+      message: v.message,
+      file: file,
+      startLine: (loc && loc.startLine) || 0,
+      tags: v.tags || [],
+    };
+  });
+}
+
+console.log(JSON.stringify(result));

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.