@salesforce/afv-skills 1.66.0 → 1.68.0

package/skills/experience-search-coordinate/references/media-route.md

@@ -109,10 +109,25 @@ Keyword/taxonomy extraction rule: see `SKILL.md` Step 4 point 2. Extract taxonom
 
 ## Search using Data 360 hybrid search (`search_electronic_media`)
 
-1. Use the user's query **as-is** — no keyword extraction or transformation needed
-2. Call `search_electronic_media(searchQuery="<user's query>")`
+1. Pass `searchQuery` **verbatim** — same language, same script as the user wrote it. No translation, no keyword extraction: translating first only makes step 2 harder, since you'd be detecting the language of your own translation instead of the user's actual words.
+2. **Determine language** — a short ISO code read directly off the user's literal wording, before any translation happens in your reasoning. Bare 2-letter codes (`en`, `fr`, `de`, `es`, `ja`, ...) cover most languages and are the validated, simpler form; a few regional splits need a country suffix instead (`pt_BR`, `zh_CN`, `zh_TW`, ...). Default to `en` only when the message is genuinely ambiguous (e.g. a bare product name) — never because translating felt natural. Use the bare 2-letter form whenever one exists — the backend accepts only the platform's own language codes, so `fr` works but `fr_FR` is rejected as invalid (`en` and `en_US` both work because `en_US` is itself a platform code).
+3. Call `search_electronic_media(searchQuery="<verbatim query>", searchLanguage="<language code>")`. **Only send `searchLanguage` if the tool's input schema actually lists it** — orgs without language-variant search enabled don't declare the input at all. When it's absent, call with `searchQuery` alone, skip the language line in the confirmation message, and skip steps 4–5 (the backend searches primary-language content only).
+4. **Offer one retry with `searchLanguage` omitted entirely — ask the user first, never retry silently — but only when the first call either:**
+   - returns **zero results**, **or**
+   - fails with an **input-validation error about the language value itself** — an unrecognized language code errors the whole call (for example, `INVALID_API_INPUT` / "Specify a valid language code, such as en_US, fr, or de.") rather than returning an empty list.
 
-Example: user query "modern luxury apartment with natural lighting" → `search_electronic_media(searchQuery="modern luxury apartment with natural lighting")`
+   **Do NOT offer this retry on a server or transport error (5xx, timeout, connection failure).** Those must fail per `SKILL.md`'s Error Handling table — omitting the language cannot fix them and would mask the real failure. The retry exists only for the two language-specific cases above.
+
+   Offer it before concluding nothing exists and before suggesting broader keywords: tell the user what happened in plain chat text (e.g. "No results found in French."), then `ask_followup_question` with options `Yes - search without language filter` / `No - stop here`. The retry is a second backend call the user didn't confirm, so they decide whether it runs. Skip the question only if the user already said, in this conversation, to fall back to any language when nothing matches theirs — then retry directly. Omitting the field makes the backend fall back to each item's own primary/default language variant instead of the requested one — so an item that only has, say, a French variant still surfaces on the retry even when the user asked in English. Only fall through to "no results" / broadening suggestions if the user declines, or the retry also comes back empty.
+5. **Read each result item's `language` field to know which language variant you actually got** (a locale string such as `en_US` or `fr`). If it differs from the language the user asked for — typically after the retry — say so explicitly when presenting that item, e.g. "No French version exists for this item — here's the original in English." Never present a fallback-language result as if it were the requested-language match; the user needs to know a substitution happened.
+
+   If `language` is **absent** on the results of a call that sent `searchLanguage`, the backend couldn't apply the language filter (for example, the org's search index predates language-variant support) and silently returned primary-language content instead — even on the first call, with no error and no empty list. Don't claim the results are in the requested language; tell the user the search couldn't be restricted to that language.
+
+This is a **strict** filter, not soft ranking like the keyword route: the backend only returns items carrying that exact language variant, and it does **not** fall back to English (or any other language) per item on its own — that's why step 4's retry exists as an explicit, user-approved second call, not something the backend does silently.
+
+Example — French input "trouve-moi une image de pinceaux depuis le CMS" → `search_electronic_media(searchQuery="trouve-moi une image de pinceaux depuis le CMS", searchLanguage="fr")`.
+
+Example of the retry — English input "give me an image of a snowboard from the CMS" → first call `search_electronic_media(searchQuery="give me an image of a snowboard from the CMS", searchLanguage="en")` returns zero results (the only snowboard item in the org has a French variant, not English) → tell the user "No results found in English." and ask whether to search without the language filter → user picks `Yes - search without language filter` → retry `search_electronic_media(searchQuery="give me an image of a snowboard from the CMS")` with `searchLanguage` omitted → the item surfaces with `language: "fr"` → tell the user: "No English version exists for this item — here's the original in French."
 
 ## Confirming the query before searching
 
@@ -130,11 +145,22 @@ I'll search for media with these parameters:
   Channels: Public
 ```
 
+**Message 1 — Data 360 hybrid search variant** (surface the detected language so the user can catch a mis-detection before the search runs — language detection is the most error-prone step of this route):
+
+```text
+I'll search Data 360 hybrid search with:
+
+  Query: trouve-moi une image de pinceaux depuis le CMS
+  Language: fr   (auto-detected — tell me if this is wrong)
+```
+
+Show `Query` exactly as the user wrote it (verbatim) and `Language` as the bare code you'll send. This route has no `Content Type` / `Keywords` / `Taxonomies` / `Channels` lines — it ignores channel scope and does its own semantic matching.
+
 **Message 2 (immediately after):** `ask_followup_question` with options `Yes - search now` / `Edit search` / `Cancel`.
 
 ## Presenting Search Results
 
-1. **Parse each call's response** — Extract all results (title and content type) and each item's full `managedContentChannelDeliveryDetails` array, merged across calls if the item appears in more than one response (per "Executing the search call(s)" above — nothing is dropped as a duplicate).
+1. **Parse each call's response** — Extract all results (title and content type) and each item's full `managedContentChannelDeliveryDetails` array, merged across calls if the item appears in more than one response (per "Executing the search call(s)" above — nothing is dropped as a duplicate). Data 360 hybrid search results have a different shape: each item carries `mediaUrl` (or a `mediaUrls` list of `{channelId, channelName, url}`) instead of `managedContentChannelDeliveryDetails`, plus a `language` field when language-variant search applied — use `language` per step 5 of "Search using Data 360 hybrid search" above.
 2. **Use `ask_followup_question`** to present ALL results as selectable **unique** options (one option per item, by identifier), grouped by content type — same grouping key as the Content Route (see `content-route.md` Step 6), never by channel. Show the title, content type, and channel on each option — do not display the URL. If an item's `managedContentChannelDeliveryDetails` array has more than one entry, show the **first** entry's channel name here as a lightweight hint only; the actual choice between channels is made after selection (see "Disambiguating channel at selection" below), not here. If more than one content type FQN is in scope, order the options by content type (the tool has no native grouping — approximate it by ordering and, where the UI allows a label, prefixing the option text with the content type). Regardless of grouping, always include the channel as a per-item suffix, e.g. `Product Launch Hero Banner (sfdc_cms__image) — Public`.
 3. **Receive the user's selection** from the tool response
 

package/skills/experience-ui-bundle-features-generate/SKILL.md

@@ -10,7 +10,7 @@ metadata:
       semver: ">=7.0.0"
     - tool: ["npm"]
       semver: ">=7.0.0"
-  accessCheck: "(OrgPreferences.Sites) && (License.ExperienceCloudCustomerCommunityCustomerCommunityPlus)"
+  accessCheck: "OrgPermissions.Networks"
 ---
 
 # UI Bundle Features

package/skills/experience-ui-bundle-mfa-configure/SKILL.md

@@ -10,7 +10,7 @@ metadata:
       semver: ">=1.6"
     - tool: ["sf"]
       semver: ">=2.0.0"
-  accessCheck: "License.ExperienceCloudCustomerCommunityCustomerCommunityLogin"
+  accessCheck: "OrgPermissions.Networks"
   relatedSkills:
     - "dx-org-permission-set-assign"
     - "experience-ui-bundle-deploy"

package/skills/field-service-data-capture-migrate/SKILL.md

@@ -18,7 +18,7 @@ metadata:
     slack:
       tools: ["slack_create_canvas", "slack_send_message"]
       semver: ">=1.0.0"
-  accessCheck: "License.FieldService"
+  accessCheck: "OrgPermissions.FieldService"
 ---
 
 # Migrate Field Service Mobile Flows to Data Capture

package/skills/platform-apex-generate/SKILL.md

@@ -7,6 +7,8 @@ metadata:
   minApiVersion: "66.0"
   relatedSkills:
     - "platform-apex-test-generate"
+    - "dx-code-analyzer-run"
+    - "integration-apex-symbol-table-query"
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
@@ -47,6 +49,7 @@ All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and a
    - Service-Selector-Domain layering, logging utilities
    - Existing classes/triggers and current trigger framework or handler pattern
    - Whether Trigger Actions Framework (TAF) is already in use
+   - Signatures of classes and built-in types you will call or extend: use `integration-apex-symbol-table-query` (API v67.0+); if unavailable, read the source
 
 2. **Choose the smallest correct pattern** (see Type-Specific Guidance below)
 
@@ -57,22 +60,22 @@ All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and a
 
 4. **Author with guardrails** -- apply every rule in the Rules section below
    - Generate `{ClassName}.cls` with ApexDoc
-   - Generate `{ClassName}.cls-meta.xml`   
+   - Generate `{ClassName}.cls-meta.xml`
 
-5. **Generate test classes** -- Load the skill `platform-apex-test-generate` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`.  Apex tests are always required to be generated to deploy. No test file creation or edits can occur without loading the  `platform-apex-test-generate` skill to generate tests.
+5. **Generate test classes** -- Load the skill `platform-apex-test-generate` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`. Apex tests are required to deploy; never create or edit test files without loading it.
 
 ### Phase 2 — Validate (required before reporting)
 
-Writing files is the midpoint, not the finish line. Steps 6 and 7 each require a tool invocation and produce output that must appear in the Step 8 report. Do not summarize or present the report until both steps have run and their output is captured.
+Steps 6 and 7 each require a tool invocation and produce output that must appear in the Step 8 report. Do not present the report until both have run and their output is captured.
 
 6. **Run code analyzer**
-   - Invoke MCP `run_code_analyzer` on all generated/updated `.cls` files.
+   - Use the `dx-code-analyzer-run` skill on all generated/updated `.cls` files.
    - Remediate all `sev0`, `sev1`, and `sev2` violations; re-run until clean.
-   - Capture the final tool output verbatim for the report.
-   - Fallback: `sf code-analyzer run --target <target>`. If both are unavailable, record `run_code_analyzer=unavailable: <error>` in the report.
+   - Keep the final tool output verbatim for the report.
+   - Fallback: `sf code-analyzer run --target <target>`. If both are unavailable, record `code_analyzer=unavailable: <error>` in the report.
 
 7. **Execute Apex tests**
-   - Run org tests including `{ClassName}Test` via `sf apex run test` or MCP.
+   - Run org tests including `{ClassName}Test` via `sf apex run test`.
    - Delegate all test generation/fixes/coverage work to `platform-apex-test-generate`; iterate until the tests pass.
    - Capture pass/fail counts and coverage percentage for the report.
    - If unavailable, record `test_execution=unavailable: <error>` in the report.
@@ -80,9 +83,9 @@ Writing files is the midpoint, not the finish line. Steps 6 and 7 each require a
 ### Phase 3 — Report
 
 8. **Report** -- use the output format at the bottom of this file.
-   - The `Analyzer` line must contain the actual Step 6 tool output (or `run_code_analyzer=unavailable: <reason>` after attempting invocation).
-   - The `Testing` line must contain the actual Step 7 results (or `test_execution=unavailable: <reason>` after attempting invocation).
-   - A report missing either line is incomplete. Always attempt the tool invocation before recording unavailable.
+   - The `Analyzer` line must contain the actual Step 6 tool output (or `code_analyzer=unavailable: <reason>` after attempting it).
+   - The `Testing` line must contain the actual Step 7 results (or `test_execution=unavailable: <reason>` after attempting it).
+   - A report missing either line is incomplete; always attempt the invocation before recording unavailable.
 
 ---
 
@@ -392,7 +395,7 @@ Files: <paths>
 Design: <pattern / framework choices>
 Workflow: all steps completed (1-8); any N/A justified
 Risks: <security, bulkification, async, dependency notes>
-Analyzer: <REQUIRED -- paste actual run_code_analyzer output or state "run_code_analyzer=unavailable: <reason>">
+Analyzer: <REQUIRED -- paste actual code analyzer output or state "code_analyzer=unavailable: <reason>">
 Testing: <REQUIRED -- paste actual test execution results (pass/fail, coverage) or state "test_execution=unavailable: <reason>">
 Deploy: <dry-run or next step>
 ```

package/skills/platform-apex-test-generate/SKILL.md

@@ -7,6 +7,7 @@ metadata:
   minApiVersion: "66.0"
   relatedSkills:
     - "platform-apex-generate"
+    - "integration-apex-symbol-table-query"
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
@@ -51,7 +52,7 @@ Always wrap the code under test in `Test.startTest()` / `Test.stopTest()`:
 
 Before generating or fixing tests, identify:
 
-- the target production class(es) under test
+- the target production class(es) under test; use the `integration-apex-symbol-table-query` skill to get their exact method signatures, fields, and inner types rather than inferring them. If the org does not support it (API v67.0+ required) or the call fails, read the source instead
 - existing test classes, test data factories, and setup helpers
 - desired test scope (single class, specific methods, suite, or local tests)
 - coverage threshold (75% minimum for deploy, 90%+ recommended)

package/skills/platform-datamask-run/SKILL.md

@@ -99,15 +99,25 @@ Prefer reusing an existing policy (fastest, no deploy):
 sf data query --use-tooling-api --target-org <alias> \
   --query "SELECT Id, DeveloperName, MasterLabel FROM DataMaskPolicy"
 ```
-If none targets the Contact PII you need, author one with the **two-step** recipe (the
+If none targets the object and fields you need, choose the fields first (below), then author one.
+
+**Choose the fields from Core's classification, not from field names alone.** Before inserting any
+`DataMaskPolicyField` row, call the field-classification operation once per target object and map each
+`recommendedPiiType` to a treatment. The steps are in `references/policy-authoring.md` ("Choosing the
+fields from Core's classification"). Any recommendation with no verified `MaskValue` token is reported
+as unmapped; never guess a `MaskValue`. Use the static table only if the call fails, and say so in the
+report.
+
+Then author one with the **two-step** recipe (the
 `DataMaskPolicy` Metadata shape is a thin shell; membership is Tooling-inserted):
 1. **Metadata-deploy the thin shell** in **mdapi format** (`--metadata-dir` + `package.xml`; a
    source-format `--source-dir` deploy fails "Could not infer a metadata type"). The shell carries
    only `<label>`, `<description>`, `<runOnRefresh>`. This creates the policy *with an active
-   revision*, which A2 requires.
+   revision*, which the Tooling inserts in the next step require.
 2. **Tooling-insert** the `DataMaskPolicyObject` (one per object) then its `DataMaskPolicyField`
-   rows. Each field row's treatment is `MaskingCategory` (`library`) + `MaskValue` (a snake_case
-   token like `first_name`, `email`, `phone`). There is **no `MaskingRuleType` column**.
+   rows. Each field row's treatment is `MaskingCategory` + `MaskValue`. For `library`, `MaskValue` is a
+   snake_case token like `first_name`, `email`, `phone`. For `characters` and `replaceRandom`, `MaskValue`
+   is the field's Salesforce type (`Text`, `Date`). There is **no `MaskingRuleType` column**.
 
 > Insert order matters: a Tooling-created parent (no active revision) makes the child insert fail
 > `INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY`. Metadata-deploy the shell first.
@@ -150,36 +160,36 @@ mid-run status as final.
 
 **Jobs are slow — expect several minutes, and poll with the bundled script.** Data Mask runs on a
 backend pool/scheduler with a **~5–10 minute floor**: even a tiny (20-row) job usually does **not**
-reach a terminal state or emit detail rows for several minutes after the run starts. This is fixed
-overhead, **not** proportional to row count. Plan the run around it — the single biggest failure mode
-is treating the job as instant, polling on a tight interval, and either timing out or writing a
-"still pending" report.
+reach a terminal state or emit detail rows for several minutes. This is fixed overhead, **not**
+proportional to row count. The biggest failure mode is treating the job as instant, polling tightly,
+and either timing out or writing a "still pending" report.
 
 Run `scripts/poll-job.sh` as a **single command** — do **not** hand-roll a SOQL poll loop:
 ```bash
 bash scripts/poll-job.sh <alias> <jobRunId>        # defaults: cap 600s (10 min), 20s interval
 ```
-It sleeps on a low-frequency interval, short-circuits the instant a ground-truth detail row appears,
-prints the terminal signal (`completed`/`failed`/`canceled`) on stdout, and exits `0` (or `1` on
-timeout). **Call it once and read its result — do not wrap it in your own retry loop**, and do not
-poll on a sub-10s interval (it just burns tool calls against a job that cannot finish sooner).
-
-**Ground truth is the detail rows, not the parent status.** The parent `DataMaskPolicyJobRun.Status`
-can **lag** — it may read `pending`/`running` for a while after masking actually finished. Once a
-`total_records_masked` (or `completed`) `DataMaskPolicyJobRunDtl` row exists, the masking is done.
-`poll-job.sh` already encodes all of this — the bounded interval and timeout, the short-circuit on
-the ground-truth detail row, and the terminal-signal exit code — so you do **not** re-implement any
-of it inline. Run the poller once, read its exit signal, then update `report.md` (the stub you wrote
-before polling) with the terminal status and the masked count from A5.
+It sleeps on a low-frequency interval, prints the terminal status (`completed` /
+`completed_with_errors` / `failed` / `canceled`) on stdout, and exits `0` (or `1` on timeout).
+**Call it once and read its result — do not wrap it in your own retry loop**, and do not poll on a
+sub-10s interval (it just burns tool calls against a job that cannot finish sooner).
+
+**The job is done only when the parent `DataMaskPolicyJobRun.Status` is terminal.** A
+`DataMaskPolicyJobRunDtl` row is not a completion signal: a `total_records_masked` row can already
+exist, reading `0`, while the parent is still `running`, so a count read mid-run is wrong. Wait for
+the poller to exit `0`, then read the detail rows (A5) and update the `report.md` stub with the
+terminal status and the masked count.
 
 ### A5. Report results from the job DETAIL object
 The parent job carries an overall status; **per-object masked counts live on the child**
-`DataMaskPolicyJobRunDtl` (linked by `DataMaskPolicyJobRunId`). Report a concrete count, not a
-fabricated one:
+`DataMaskPolicyJobRunDtl` (linked by `DataMaskPolicyJobRunId`). `DataMaskPolicyJobRunDtl` has **no
+`Status` column** — the status lives in `Type`/`Subtype`, with the count itself in `Value` (a
+string). Report a concrete count, not a fabricated one:
 ```bash
 sf data query --target-org <alias> \
-  --query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
+  --query "SELECT ObjectReference, Type, Subtype, Value FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>' ORDER BY Timestamp"
 ```
+Expect one `status_update` row per `Subtype` (`loaded`, `completed`, `total_records_masked`) for
+each target object; `total_records_masked`'s `Value` is the masked count.
 
 **Report only what the rows literally show — do not overstate granularity.** The detail rows are
 **object-level** status_update entries (`loaded`, `completed`, `total_records_masked` for the object,
@@ -199,45 +209,28 @@ just to cancel it. Steps B1–B4 are all required.
 
 ### B1. Confirm sandbox + identify the run to cancel
 Confirm the org is a sandbox (`sf org display`) and get the `jobRunId` of the run to abort — the one
-the user is asking to cancel. **Capture its `DataMaskPolicyId` too** — you need it to start a
-replacement run if the abort window is missed (B2 exit 3 / exit 1). If they just started it, use that
-id; otherwise query for the active run:
+the user is asking to cancel. **Capture its policy Id too** — you need it to start a replacement run
+if the abort window is missed (B2 exit 3 / exit 1). If they just started it, use that policy id
+directly; otherwise query for the active run:
 ```bash
 sf data query --target-org <alias> \
-  --query "SELECT Id, Status, DataMaskPolicyId FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
+  --query "SELECT Id, Status, PolicyName FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
 ```
-Note the `DataMaskPolicyId` (`8dm` prefix) of the run you pick — that is the `<policyId>` A3 needs.
-
-### B2. Wait for the job to be `running` (the only abortable state)
-You can only abort while `DataMaskPolicyJobRun.Status` is `running`. A `pending`/`scheduled` job
-`409`s; a terminal one is already done. Poll for the `running` window with the bundled poller in its
-**`running` mode** — it exits the instant the status reads `running` (unlike the default mode, which
-waits for a terminal state), so it will not block past the abortable window:
+`DataMaskPolicyJobRun` has **no `DataMaskPolicyId` lookup field** — the only link back to the policy
+is the human-readable `PolicyName` (`MasterLabel`). Resolve the Id from it via the Tooling API:
 ```bash
-POLL_MODE=running bash scripts/poll-job.sh <alias> <jobRunId> 900 15
+sf data query --use-tooling-api --target-org <alias> \
+  --query "SELECT Id, DeveloperName FROM DataMaskPolicy WHERE MasterLabel = '<PolicyName>'"
 ```
-The cap is **900s (15 min)**, above the ~5–10 min scheduling floor so a slow-to-start job still gets
-caught. Handle every exit:
-- **Exit `0`** (prints `running`) → go straight to B3.
-- **Exit `3`** → the job raced to a terminal state before `running` was caught; the abort window is
-  gone. Start a fresh run against the policy you captured in B1 (A3 with that `<policyId>`), then
-  return here and poll the **new** `jobRunId`.
-- **Exit `1`** (timeout — the cap expired) → re-query the job's status:
-  ```bash
-  sf data query --target-org <alias> \
-    --query "SELECT Id, Status FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
-  ```
-  If it is still non-terminal (`pending`/`scheduled`/`running`), re-run the poller **once** more (same
-  command) to continue waiting. If it is `running`, go to B3. If it is terminal, treat it like exit 3
-  — start a fresh run (A3 with the B1 `<policyId>`) and poll the new job.
-
-Because of the ~5–10 min pool floor the `running` window is usually minutes wide, so there is time to
-catch it; do not poll with no delay.
-
-> **If no run is currently in progress** (the job already completed, or you must reproduce a
-> run→cancel flow end to end), start one first with A3, then return here — poll it to `running` and
-> abort **that** live job. Never substitute an older, already-terminal job to "show" a cancel; the
-> abort must target the run that is actually live.
+That `Id` (`8dm` prefix) is the `<policyId>` A3 needs.
+
+### B2. Wait for the job to be `running` (the only abortable state)
+Poll with `POLL_MODE=running` (cap 900s, 15s interval). Full command, exit-code handling (0 / 3 / 1),
+and the re-query-on-timeout steps are in `references/run-and-abort.md` section 5. A `pending` or
+`scheduled` job `409`s on abort, so do not abort until the poller exits `0`.
+
+If no run is in progress, start one with A3 and abort **that** live job. Never substitute an older,
+already-terminal job to "show" a cancel.
 
 ### B3. Abort via the run API
 Abort via the run API — **not** by DML/delete on the job record:
@@ -263,14 +256,8 @@ Cancellation is asynchronous. **Re-query** `DataMaskPolicyJobRun` and confirm `S
 | Rule | Rationale |
 |------|-----------|
 | Run each `sf` command **bare** — never add a pipe or redirect of any kind (`\|`, `\| python3`, `\| grep`, `2>&1`, `2>/dev/null`, `> file`) | `sf ... --json` already prints clean JSON on stdout; read it directly. A redirect/pipe trips an unbypassable shell-safety guard that silently stalls the whole run to timeout. Never post-process with `python3`/`grep`/`jq`, and never suppress stderr — even if a command prints a warning, the `--json` payload on stdout is still valid; just parse it as-is |
-| Never use standard SOQL / `sobject describe` on `DataMaskPolicy*` config objects | They return `INVALID_TYPE` / `NOT_FOUND` — use Tooling API or MDAPI |
-| Read masked counts from `DataMaskPolicyJobRunDtl`, never invent them | The child detail is the source of truth for per-object results |
-| Only `completed` / `completed_with_errors` / `failed` are terminal | Reporting `running`/`scheduled` as final is wrong |
 | Abort only via the run-API abort endpoint | DML/delete on the job record is not a real abort and corrupts state |
-| Always re-query status after abort and confirm `canceled` | An abort call returning 200 is not proof the job stopped |
-| Data Mask runs on sandboxes only | Run/abort endpoints `403` on production |
 | Use API version `v67.0` or later, and no `/connect/` segment | The run/abort endpoints are `/services/data/v67.0/platform/data-resilience/data-mask/...` — a `connect` segment or a pre-v67 version returns `NOT_FOUND` |
-| Poll via `scripts/poll-job.sh` (one call), never a hand-rolled SOQL loop | The script caps attempts and short-circuits on the ground-truth detail row; a manual loop against the lagging parent status is the #1 cause of a run timing out with no report |
 
 ---
 
@@ -278,15 +265,9 @@ Cancellation is asynchronous. **Re-query** `DataMaskPolicyJobRun` and confirm `S
 
 | Issue | Resolution |
 |-------|------------|
-| `sf sobject describe DataMaskPolicy` → `NOT_FOUND` | It's a Tooling/MDAPI entity — query with `--use-tooling-api`, don't retry standard API |
-| `SELECT ... FROM DataMaskPolicy` → `INVALID_TYPE` | Same cause — use Tooling API for the policy; standard API only for `DataMaskPolicyJobRun`/`Dtl` |
-| Run start returns `409` | A run is already in progress for that policy — poll the existing one or wait for it to finish |
-| Abort returns `409` "status=PENDING" | The job is still `pending`/`scheduled`, not yet `running` — keep polling and abort only once it reads `running`; don't give up on the abort |
 | Small job finishes before you can abort it | The `running` window is seconds on a small sandbox — start a fresh run and poll tightly; never substitute a previously-aborted job to fake the flow |
-| Abort returns `200` but SOQL status still `running` | Cancellation is async — keep polling the SOQL status until `canceled`; don't report success early |
-| Run API says `CANCELED` but SOQL says `running` | Case + surface differ: the run API is UPPERCASE, SOQL picklist is lowercase. Trust the SOQL value for terminal state |
-| Job "finished" instantly | Re-check: `scheduled` is not terminal. Poll until a terminal value actually appears |
-| Run/abort endpoint `NOT_FOUND` | The path must be `/services/data/v67.0/platform/data-resilience/data-mask/...` — no `/connect/` segment, and version `v67.0`+ (Core 262). See `references/api-surface.md` |
+| Run API says `CANCELED` but SOQL says `running` | Case + surface differ (run API UPPERCASE, SOQL lowercase). Trust the SOQL value for terminal state |
+| Run start returns `409` or abort `409` | Run start: a run is already active for that policy. Abort: the job is not `running` yet. Details in `references/run-and-abort.md` failure table |
 
 ---
 

package/skills/platform-datamask-run/references/api-surface.md

@@ -30,8 +30,9 @@ authoritative map.
 > then (2) Tooling-insert the object + field rows against it. The Metadata deploy must come first:
 > it creates the policy with an active revision, without which the Tooling child insert fails
 > `INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY`. See `policy-authoring.md` for the full recipe.
-> `DataMaskPolicyField` treatment columns are `MaskingCategory` (`library` / `replaceRandom`) +
-> `MaskValue` (a snake_case library token) — there is **no `MaskingRuleType` column**.
+> `DataMaskPolicyField` treatment columns are `MaskingCategory` (`library` / `characters` /
+> `replaceRandom`) + `MaskValue` (a snake_case library token for `library`, or the field's Salesforce
+> type such as `Text` / `Date` for `characters` / `replaceRandom`) — there is **no `MaskingRuleType` column**.
 
 > **Schedule fields live ON the policy** — there is no separate schedule entity. `RunFrequency`
 > (`once` / `daily` / `weekly` / `monthly`), `ScheduledStart`, and `RunOnRefresh` are fields on
@@ -64,11 +65,16 @@ sf data query --use-tooling-api --target-org <alias> \
 
 # RIGHT — job + job-detail via standard API:
 sf data query --target-org <alias> \
-  --query "SELECT Id, Status, Type, TotalRecords FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
+  --query "SELECT Id, Status, Type, PolicyName FROM DataMaskPolicyJobRun ORDER BY CreatedDate DESC LIMIT 5"
 sf data query --target-org <alias> \
-  --query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
+  --query "SELECT ObjectReference, Type, Subtype, Value FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>' ORDER BY Timestamp"
 ```
 
+`DataMaskPolicyJobRun` has **no `TotalRecords`** and **no `DataMaskPolicyId`** lookup field —
+resolve the policy from `PolicyName` (`MasterLabel`) via the Tooling API instead.
+`DataMaskPolicyJobRunDtl` has **no `Status`** column — status lives in `Type`/`Subtype`, and the
+masked count is `Value` on the row where `Subtype = 'total_records_masked'`.
+
 ## Status picklist values (`DataMaskPolicyJobRun.Status`)
 
 ```text

package/skills/platform-datamask-run/references/policy-authoring.md

@@ -91,13 +91,62 @@ Each `DataMaskPolicyField` carries a `MaskingCategory` plus a `MaskValue` — th
 `MaskingRuleType` column** (older docs claiming values like `RandomEmail` / `RandomPhoneNumber`
 were wrong; that column does not exist).
 
-- `MaskingCategory` — `library` (pick a value from the built-in library, the common case) or
-  `replaceRandom` (random replacement).
-- `MaskValue` — a snake_case library token identifying the value set. Verified tokens include:
-  `first_name`, `last_name`, `email`, `phone`, `street`, `city`, `state`, `postal_code`,
-  `country`, `account_name`, `URL`.
-
-## Choosing treatments
+- `MaskingCategory` — `library` (pick a value from the built-in library, the common case),
+  `characters` (random characters), or `replaceRandom` (random replacement).
+- `MaskValue` depends on the category:
+  - `library` — a snake_case library token identifying the value set. Verified tokens include:
+    `first_name`, `last_name`, `email`, `phone`, `street`, `city`, `state`, `postal_code`,
+    `country`, `account_name`, `URL`.
+  - `characters` and `replaceRandom` — the field's Salesforce type (for example `Text`, `Date`).
+    Left empty, the run fails with `UNKNOWN_EXCEPTION` ("Mask Value is required for Replace Random
+    field").
+
+## Choosing the fields from Core's classification
+
+The Data Mask UI's "Automatic PII rules" are driven by a per-field `recommendedPiiType` that Core's
+classifier computes. Use the same source here so the skill and the UI recommend the same fields. Do
+this once per target object, before inserting any `DataMaskPolicyField` row.
+
+1. **Call the classification operation** through the `project-codey` server's `dispatch_readonly`
+   tool. It takes a `path`, not an operationId: `path`
+   `/headless/invoke/platform/datamask/data-mask-policy/get-object-fields-with-masking-info`, `method`
+   `GET`, and `query_params` `{objectApiName: <object>, includePicklistValues: false,
+   includeFilterOnlyFields: false}` (for example `objectApiName: "Contact"`). Omit `policyObjectId` (a
+   new object has no `DataMaskPolicyObject` row yet). If this path 404s, re-resolve it with `find_route`
+   rather than guessing. The `.../data-mask-policy-builder/...` route serves the same operation but does
+   not take the two picklist/filter params.
+2. **Read the response.** The result is `{status_code, body}`, where `body` is an array with one entry
+   per field. Each entry carries `apiName`, `label`, `type`, and `recommendedPiiType` (`null` when Core
+   has no recommendation). Any other shape counts as a failed call (step 4).
+3. **Map each recommendation to a treatment.** Core returns tokens such as `last_name`, `street`,
+   `phone`, `characters`, and `replaceRandom`. Compare `recommendedPiiType` case-insensitively with the
+   verified `MaskValue` tokens in "Field treatment columns" above. `characters` and `text` are the same
+   category.
+   - A verified token → `MaskingCategory=library`, `MaskValue=<that token>`.
+   - `characters`/`text` → `MaskingCategory=characters`. `replaceRandom` → `MaskingCategory=replaceRandom`.
+     Both also require `MaskValue` = the field's Salesforce type as Core reports it in `type` (for example
+     `Text`, `Date`). The UI's "Mask With" menu offers `Random Characters` for `characters`.
+   - Any other recommendation (for example `title`, `full_name`, `full_address`, `credit_card`, `ssn`,
+     `password`, `date`, `numberRange`) has no `MaskingCategory` or verified token here. **Report it as
+     unmapped. Do not guess a `MaskValue`.**
+   - A field with no `recommendedPiiType` is not masked. List it in the report.
+4. **Fall back only when the call fails** (refused, errored, the `project-codey` server is unavailable,
+   or the response shape is unrecognized). Then use the static table below and state in the report that
+   the field list came from the static table, not from Core. When the call succeeds, Core's answer is
+   authoritative. Do not add fields from the static table.
+
+## Fallback treatments (static table)
+
+Use this table **only** when the classification call in "Choosing the fields from Core's classification"
+fails. When the call succeeds, use Core's `recommendedPiiType` and skip this table. The table is narrower than Core:
+
+- It covers only the standard fields listed below. It does not apply Core's label, type, or encryption
+  rules, so it misses fields Core does recommend (for Contact: the Other* address fields, `Fax`,
+  `HomePhone`, `OtherPhone`, `AssistantPhone`).
+- Core's type-based fallback classifies some text fields as `characters` (for Contact, `AssistantName`)
+  and some date fields as `replaceRandom` (for Contact, `Birthdate`). Both map to their `MaskingCategory`
+  value with `MaskValue` set to the field's Salesforce type (`Text` for AssistantName, `Date` for
+  Birthdate), so they are masked, not reported as unmapped.
 
 Match the `MaskValue` to the field's semantics — do **not** apply one blanket replacement:
 

package/skills/platform-datamask-run/references/run-and-abort.md

@@ -48,28 +48,35 @@ Capture `jobRunId`. A `409`/`CONFLICT` means a run is already active for this po
 ## 3. Poll to terminal
 ```bash
 sf data query --target-org <alias> \
-  --query "SELECT Id, Status, Type, TotalRecords FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
+  --query "SELECT Id, Status, Type FROM DataMaskPolicyJobRun WHERE Id = '<jobRunId>'"
 ```
-Repeat on a bounded interval until `Status` is one of `completed`, `completed_with_errors`,
-`failed`. `scheduled`/`running` are NOT terminal. `scripts/poll-job.sh` automates this with a
-timeout.
+`DataMaskPolicyJobRun` has **no `TotalRecords` field** — there is no record-count column on the
+parent; the masked count lives on the child detail rows (step 4). Repeat the status query on a
+bounded interval until `Status` is one of `completed`, `completed_with_errors`, `failed`.
+`scheduled`/`running` are NOT terminal. `scripts/poll-job.sh` automates this with a timeout.
 
 ## 4. Report from the detail object
-Per-object masked results live on the child, not the parent:
+Per-object masked results live on the child, not the parent. `DataMaskPolicyJobRunDtl` has **no
+`Status` column** — the status lives in `Type`/`Subtype`, with the count itself in `Value` (a
+string):
 ```bash
 sf data query --target-org <alias> \
-  --query "SELECT Id, DataMaskPolicyJobRunId, Status FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>'"
+  --query "SELECT ObjectReference, Type, Subtype, Value FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '<jobRunId>' ORDER BY Timestamp"
 ```
-Report the concrete masked-record count and per-object success/failure from these rows. Do not
-report a number you did not read from here.
+Expect one `status_update` row per `Subtype` (`loaded`, `completed`, `total_records_masked`) for
+each target object; `total_records_masked`'s `Value` is the masked count. Report the concrete
+masked-record count and per-object success/failure from these rows. Do not report a number you did
+not read from here.
 
 ## 5. Abort the currently-running job — ONLY when the user asked to cancel
 Steps 5–7 are the **abort** flow. Run them **only when the prompt explicitly asks to cancel/abort**
 a run — a "create and run" or "edit and run" task is complete after step 4.
 
 Aborting is an **on-demand action against a job that is already in progress**: take that job's
-`jobRunId` (and note its `DataMaskPolicyId` — you need it to start a replacement run if the window is
-missed), wait for `DataMaskPolicyJobRun.Status = running`, and go straight to the abort (step 6).
+`jobRunId` (and note its policy Id — you need it to start a replacement run if the window is
+missed; `DataMaskPolicyJobRun` has no direct policy lookup field, so resolve it from the job's
+`PolicyName` via `SELECT Id FROM DataMaskPolicy WHERE MasterLabel = '<PolicyName>'` against the
+Tooling API), wait for `DataMaskPolicyJobRun.Status = running`, and go straight to the abort (step 6).
 You can only abort a running job. Do **not** use the terminal poll from step 3 here — it waits until
 the job is *done*. Use the poller's `running` mode, which returns the instant the job is abortable:
 ```bash

package/skills/platform-datamask-run/scripts/poll-job.sh

@@ -17,10 +17,10 @@
 # so the default cap is 600s (10 min) with a 20s interval to keep the query volume low. Do NOT poll
 # on a tight (sub-10s) interval — it just burns tool calls against a job that cannot finish sooner.
 #
-# TERMINAL MODE: The parent DataMaskPolicyJobRun.Status can LAG the real job state (it may read
-# `pending`/`running` for a while after masking finished). So this poller ALSO checks
-# DataMaskPolicyJobRunDtl: once a `total_records_masked` detail row exists, the job is effectively
-# done and we stop, even if the parent status hasn't caught up. Ground truth is the detail rows.
+# TERMINAL MODE: exits only on a terminal PARENT status. A `total_records_masked` detail row is NOT a
+# completion signal: it can already exist, reading `0`, while the parent is still `running`, so
+# stopping on the first row reports a count for a job that has not finished. Read the detail rows
+# only AFTER this script exits.
 #
 # RUNNING MODE (for abort): exits the instant the parent status reads `running` — the only state in
 # which the abort endpoint accepts the request (a `pending`/`scheduled` job 409s). Because the pool
@@ -30,7 +30,7 @@
 # start a fresh run rather than abort a job that already finished.
 #
 # Exit codes:
-#   terminal mode: 0 = terminal status OR masked-count detail row observed (signal on stdout);
+#   terminal mode: 0 = terminal parent status observed (printed on stdout);
 #                  1 = timed out; 2 = bad args.
 #   running mode:  0 = `running` observed (prints `running`); 1 = timed out; 2 = bad args;
 #                  3 = job reached a terminal state before `running` was seen (prints that status).
@@ -63,12 +63,15 @@ is_terminal() {
 
 elapsed=0
 while (( elapsed < MAX_SECONDS )); do
-  status="$(
-    sf data query --target-org "$ORG" \
-      --query "SELECT Status FROM DataMaskPolicyJobRun WHERE Id = '${JOB_ID}'" \
-      --json 2>/dev/null \
-    | python3 -c "import json,sys; r=json.load(sys.stdin).get('result',{}).get('records',[]); print(r[0]['Status'] if r else 'UNKNOWN')"
-  )"
+  # CSV is a header line then one value per row, so bash can read it with no pipe and no
+  # post-processor. stderr is left attached so an auth or alias failure is visible; a failed
+  # query only skips this tick, it does not end the poll.
+  csv="$(sf data query --target-org "$ORG" \
+    --query "SELECT Status FROM DataMaskPolicyJobRun WHERE Id = '${JOB_ID}'" \
+    --result-format csv)" || csv=""
+  status=""
+  { IFS= read -r _; IFS= read -r status; } <<< "$csv" || true
+  status="${status:-UNKNOWN}"
   echo "[poll-job] ${JOB_ID} status=${status} (${elapsed}s/${MAX_SECONDS}s) mode=${POLL_MODE}"
 
   if [[ "$POLL_MODE" == "running" ]]; then
@@ -88,19 +91,6 @@ while (( elapsed < MAX_SECONDS )); do
       echo "$status"
       exit 0
     fi
-
-    # Ground-truth check: a masked-count detail row means the job finished even if the parent lags.
-    masked="$(
-      sf data query --target-org "$ORG" \
-        --query "SELECT Value FROM DataMaskPolicyJobRunDtl WHERE DataMaskPolicyJobRunId = '${JOB_ID}' AND Subtype = 'total_records_masked'" \
-        --json 2>/dev/null \
-      | python3 -c "import json,sys; r=json.load(sys.stdin).get('result',{}).get('records',[]); print(r[0]['Value'] if r else '')"
-    )"
-    if [[ -n "$masked" ]]; then
-      echo "[poll-job] detail row total_records_masked=${masked} — job effectively complete (parent status=${status})"
-      echo "completed"
-      exit 0
-    fi
   fi
 
   sleep "$INTERVAL"
@@ -110,6 +100,6 @@ done
 if [[ "$POLL_MODE" == "running" ]]; then
   echo "[poll-job] TIMEOUT after ${MAX_SECONDS}s — job never reached 'running'" >&2
 else
-  echo "[poll-job] TIMEOUT after ${MAX_SECONDS}s — neither terminal status nor masked-count detail row observed" >&2
+  echo "[poll-job] TIMEOUT after ${MAX_SECONDS}s — job never reached a terminal status" >&2
 fi
 exit 1