@salesforce/afv-skills 1.67.0 → 1.68.0

package/skills/education-cloud-domain-configure/SKILL.md

@@ -17,7 +17,7 @@ metadata:
     - "platform-metadata-deploy"
     - "platform-permission-set-generate"
     - "platform-validation-rule-generate"
-  accessCheck: "License.EducationCloud"
+  accessCheck: "OrgPermissions.EducationCloud"
 ---
 
 # Configuring Education Cloud Domains

package/skills/education-cloud-multi-campus-configure/SKILL.md

@@ -8,7 +8,7 @@ metadata:
     - "Education"
   relatedSkills:
     - "education-cloud-domain-configure"
-  accessCheck: "License.EducationCloud"
+  accessCheck: "OrgPermissions.EducationCloud"
   mcpTools:
     headless-360:
       tools: ["describe", "discover", "dispatch", "dispatch_readonly"]

package/skills/education-cloud-student-recruitment-agent-configure/SKILL.md

@@ -18,7 +18,7 @@ metadata:
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
-  accessCheck: "(OrgPermissions.EinsteinForEducationCloud) && (License.Agentforce)"
+  accessCheck: "(OrgPermissions.EinsteinForEducationCloud) && (OrgPermissions.EinsteinAgentPlatform)"
 ---
 
 # Configuring the Education Cloud Student Recruitment Agent

package/skills/experience-design-validate/SKILL.md

@@ -3,7 +3,7 @@ name: experience-design-validate
 description: "Use this skill to run a visual-craft audit of a rendered UI and produce an evidence-grounded Craft Report across Useful, Usable, Reliable, Coherent, and Well-Crafted. Invoke it for craft audits, visual critiques, design comparisons, felt-quality reviews, or visual-craft readiness checks on screenshots (.png, .jpg, .jpeg, .webp, .gif), Figma frames, rendered prototypes, and live URLs. Do not use it for source-code review, SLDS compliance (use design-systems-slds-validate), or accessibility compliance (use experience-accessibility-validate)."
 metadata:
   version: "1.0"
-  domains: ["Experience"]
+  domains: ["Experience", "Design Systems"]
   relatedSkills:
     - "design-systems-slds-validate"
     - "experience-accessibility-validate"

package/skills/experience-search-coordinate/SKILL.md

@@ -14,6 +14,7 @@ metadata:
       tools:
         - get_content_types_for_workspace
         - search_content_cms_channels
+        - search_digital_content
         - search_electronic_media
         - search_media_cms_channels
       semver: ">=1.0.0"
@@ -113,13 +114,18 @@ Routes search requests to the correct sub-workflow — structured CMS content or
 
 Follow this sequence for each intent Step 2 routed here. The content type FQN(s) are already known from Step 2.
 
-1. **Build the search query:**
-   - **Extract keywords** — concrete nouns and named subjects that would appear in the content's title or body. Use domain-specific synonyms, max 10 terms, joined with ` OR `. E.g. "blog posts about sustainable business practices" → `sustainable OR sustainability OR business OR environmental`.
-   - **Extract taxonomies** — descriptive qualities, categories, or topical tags only (adjectives, categories, attributes — not concrete nouns). Stringify as `{"OR": ["term1", "term2"]}`, or `"{}"` if none apply. E.g. "sustainable business practices and environmental responsibility" → `{"OR": ["Business", "Corporate", "Environment", "Responsibility"]}`; "FAQs about password resets" → `"{}"` (no descriptive/categorical terms).
-   - Load `assets/search-payload-template.json` for the request payload structure. Set `contentTypeFqn` to the comma-separated FQN list collected in Step 2. `contentAccessScope` and `channelIds` are **mutually exclusive** — never send both in the same call — so they're set per-call in point 3 below, not here.
-2. **Confirm with the user** — required two-message pattern (labeled-parameters chat message, then `ask_followup_question` with `Yes - search now` / `Edit search` / `Cancel`). Never put the labeled list inside `ask_followup_question`'s text — it strips formatting. → Read `references/content-route.md` § "Confirming the query before searching" for templates.
-3. **Execute the search call(s)** per the scope from Step 1 — one call for public-only scope, two (public + channel-scoped) when a `channelId` is in scope. → Read `references/content-route.md` § "Executing the search call(s)" before parsing results — array/merge rules.
-4. **Present up to 5 unique results total** (de-duplicated by `managedContentKey` for display only — an item found under more than one channel still appears once here), grouped by content type, with a `Load More` option if more remain. Each item shows its **Channel** as a per-item field — never the grouping key:
+1. **Present search sources via `ask_followup_question` before any tool call** — only sources whose tools you have, plus "Other"; wait for the choice. → Read `references/content-route.md` § "Presenting available search sources".
+2. **Build the query, then confirm before searching:**
+   - **Search using keywords** (`search_content_cms_channels`):
+     - **Extract keywords** — concrete nouns and named subjects likely in the title or body, plus domain synonyms; max 10, joined with ` OR `. E.g. "blog posts about sustainable business practices" → `sustainable OR sustainability OR business OR environmental`.
+     - **Extract taxonomies** — descriptive qualities, categories, or topical tags only (not concrete nouns), stringified as `{"OR": ["term1", "term2"]}`, or `"{}"` if none.
+     - Payload: `assets/search-payload-template.json`, `contentTypeFqn` = the comma-separated FQN list from Step 2. `contentAccessScope` and `channelIds` are **mutually exclusive** — never both in one call — so they're set per call in point 3.
+   - **Search using Data 360 hybrid search** (`search_digital_content`): verbatim `searchQuery`; bare ISO `searchLanguage` only if the schema lists it. On zero results or a language error, ask the user before one retry without it → `references/content-route.md`.
+   - **Other** — ask for a direct URL, asset library path, or system to check (no tool call, no confirmation).
+
+   Confirm via the two-message pattern (`Yes - search now` / `Edit search` / `Cancel`). → Read `references/content-route.md` § "Confirming the query before searching".
+3. **Execute the search call(s)** — keyword search: one call for public-only scope, two (public + channel-scoped) when a `channelId` is in scope. Hybrid: one call, no channel scope. → Read `references/content-route.md` § "Executing the search call(s)" (keyword) or the hybrid section (field mapping) before parsing results.
+4. **Present up to 5 unique results total** (de-duplicated by `managedContentKey` for display only — an item found under more than one channel still appears once here), grouped by content type, with a `Load More` option if more remain (keyword search only). Each item shows its **Channel** as a per-item field — never the grouping key:
 
    ```text
    I found 3 content items:
@@ -162,7 +168,7 @@ Follow this sequence for each intent Step 2 routed here. The media content type
 When a request mixes media and content intents, run the two routes **sequentially, each to full completion, not interleaved and not merged into one combined presentation**:
 
 1. **Media Route first** — for every media intent, run Step 4 in full: present sources, build/confirm the query, search, present results, let the user select, and (point 6) offer the `experience-cms-content-render` hand-off (Yes/No). Finish this entire route — including the offer — before starting the Content Route.
-2. **Content Route second** — for every content intent, run Step 3 in full: build/confirm the query, search, present results grouped by content type (channel shown per-item), let the user select, and (point 6) offer the `experience-cms-content-render` hand-off if a uiBundle channel is in scope.
+2. **Content Route second** — for every content intent, run Step 3 in full: present sources, build/confirm the query, search, present results grouped by content type (channel shown per-item), let the user select, and (point 6) offer the `experience-cms-content-render` hand-off if a uiBundle channel is in scope.
 
 Each route's results are labeled and presented on their own (e.g. "Images:" for the Media Route's output, then "Articles:" for the Content Route's) — never merge the two into one undifferentiated list, and never hold Media Route's results back to present alongside Content Route's.
 
@@ -170,12 +176,12 @@ Each route's results are labeled and presented on their own (e.g. "Images:" for
 
 | Error | Response |
 |---|---|
-| No `search_content_cms_channels`/`search_media_cms_channels` tools found via introspection | "No content search connection is configured. Please connect a content-readonly MCP server." |
+| No content or media search tools (keyword or hybrid) found via introspection | "No content search connection is configured. Please connect a content-readonly MCP server." |
 | Neither media tool available | "No automated media search sources are currently configured. Please provide a direct URL or asset library path." |
 | `metadata-grounding` unavailable or no content types match | Apply the fallback chain in `references/content-type-discovery.md` — do not block or ask for an FQN |
 | No search results (either route) | "No [content/media] found. Try broader keywords, removing descriptive terms, or a different [content type/source]." |
 | Invalid user selection | Re-display options and ask again |
-| Tool returns error (invalid input, missing argument, or otherwise) | Show error message, offer retry with corrected parameters **on that same tool — never fall through to the other route's search tool as a workaround** (see Key Principle 3); hybrid language errors: offer one no-language retry, with the user's OK (see media route) |
+| Tool returns error (invalid input, missing argument, or otherwise) | Show error message, offer retry with corrected parameters **on that same tool — never fall through to the other route's search tool as a workaround** (see Key Principle 3); hybrid language errors: offer one no-language retry, with the user's OK (see each route's reference) |
 | Search tool on the connected server returns a server error (5xx, timeout, connection failure — not "no results") | **Fail the call — do NOT silently retry against a different server.** Tell the user to check that server's connection/session and wait before retrying. |
 
 **Never silently fail on a route the user asked for.** If one route in a mixed request comes up empty, still present the other route's results and say so explicitly. This does not mean substituting a different server when the connected one errors — see the server-error row above.
@@ -186,7 +192,7 @@ Each route's results are labeled and presented on their own (e.g. "Images:" for
 2. **Search first, route second** — `search_metadata` + `query_metadata` decide the route; fall back to `get_content_types_for_workspace`, then intent wording, only when that comes up empty (Step 2)
 3. **Never cross-route, including on failure** — content requests never hit media search tools and vice versa; if a route's search tool errors for any reason, fix and retry that same tool or stop and report the error — never fall through to the other route's tool as a workaround
 4. **Metadata grounding is mandatory for content** — discover content type FQNs dynamically, never hardcode them
-5. **Media route starts text-only** — present sources and wait before any tool call
+5. **Both routes start text-only** — present sources and wait before any tool call
 6. **Confirm before searching (both routes)** — user approves query parameters before execution
 7. **Never auto-select** — always wait for user choice, across channel scope and both routes
 8. **Run mixed requests sequentially, Media Route first** — complete it fully (including the render offer) before starting the Content Route; present each route's results as its own labeled set, never merged
@@ -195,4 +201,4 @@ Each route's results are labeled and presented on their own (e.g. "Images:" for
 11. **Never fail over to a different server on a server error** — fail the call and tell the user to check that server's session; don't silently retry elsewhere
 12. **Group by content type, never by channel** — in both routes, channel is always a per-item field, never the group heading
 13. **Disambiguate channel at selection, not before** — an item is shown once at presentation regardless of its delivery-details array length; only after selection do you ask which channel's copy to use, one option per entry by `managedContentChannelDetails.name`, in both routes
-14. **Unauthenticated URL is public-channel-only** — `PUBLIC_UNAUTHENTICATED`/`COMMUNITY` entries only; never a `WEB_APP` (uiBundle) entry's `contentUrl`, in either route
+14. **Unauthenticated URL is public-channel-only** — `PUBLIC_UNAUTHENTICATED`/`COMMUNITY` entries only; never a `WEB_APP` (uiBundle) entry's `contentUrl`, in either route. A hybrid entry on a Step 1 uiBundle `channelId` counts as `WEB_APP`

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

@@ -1,5 +1,22 @@
 # Content Route — Full Reference
 
+## Presenting available search sources
+
+Before any tool call, dispatch `ask_followup_question` offering only the sources whose tools you actually have (via introspection), plus "Other". Each is its own option — never numbered lines inside the question text:
+
+```text
+question: "How would you like to search for content?"
+options:
+  - "Search using keywords — Search Salesforce CMS by keywords and taxonomies"
+  - "Search using Data 360 hybrid search — Semantic (vector + keyword) search across Salesforce CMS and connected DAMs"
+  - "Other — Provide your own URL, asset library path, or system to check"
+```
+
+Wait for the user's selection. Do not call any tool before this point. Then follow the matching branch:
+- **Search using keywords** → `search_content_cms_channels` (build keywords + taxonomies, confirm, execute per scope — see below).
+- **Search using Data 360 hybrid search** → `search_digital_content` (verbatim query + bare ISO `searchLanguage` when the schema lists it — see "Search using Data 360 hybrid search" below).
+- **Other** → ask for a direct URL, asset library path, or specific system to check. No confirmation step, since no tool is called.
+
 ## Confirming the query before searching
 
 Required two-message pattern, same turn:
@@ -69,6 +86,67 @@ Even though `contentUrl` is present, this item's only entry is `WEB_APP` — the
 
 The multi-channel case is not "one entry from the public call, one from the channel-scoped call" — it's whatever the array actually contains, however many entries that is.
 
+## Search using Data 360 hybrid search (`search_digital_content`)
+
+Chosen when the user picked "Search using Data 360 hybrid search" at the source step. Data 360 hybrid search (vector + keyword) runs across Salesforce CMS and any connected third-party CMS/DAM.
+
+1. Pass `searchQuery` **verbatim** — same language, same script as the user wrote it. No translation, no keyword extraction, no ` OR `-joining, no `taxonomyExpression`, no `contentTypeFqn`/`contentAccessScope`/`channelIds`, no pagination. 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. **Data 360 hybrid search ignores channel scope entirely** — there is no public vs. channel-scoped split. Make a **single call** regardless of whether a `channelId` is in scope from Step 1: `search_digital_content(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.
+
+   **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. This is the same policy as the Media Route's hybrid search (`media-route.md`). 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 un article sur les pinceaux depuis le CMS" → `search_digital_content(searchQuery="trouve-moi un article sur les pinceaux depuis le CMS", searchLanguage="fr")`.
+
+Example of the retry — English input "give me a blog post about a snowboard from the CMS" → first call `search_digital_content(searchQuery="give me a blog post about a snowboard from the CMS", searchLanguage="en")` returns zero results (the only snowboard article 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_digital_content(searchQuery="give me a blog post about 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."
+
+Still confirm first via the two-message pattern — Message 1 surfaces 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 un article sur les 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. Then `ask_followup_question` with `Yes - search now` / `Edit search` / `Cancel`, exactly as for keyword search.
+
+### Parsing the `search_digital_content` response
+
+The response shape differs from `search_content_cms_channels`. Map each result to the same content-route fields the rest of this reference uses, so "Disambiguating channel at selection", display, and the render hand-off all work unchanged:
+
+| `search_digital_content` field | Content-route equivalent |
+|---|---|
+| `contentName` | `title` |
+| `contentId` | `managedContentId` |
+| `contentKey` | `managedContentKey` |
+| `contentTypeFqn` | `contentType` |
+| `contentUrls[]` → each `{ channelName, channelId, url }` | `managedContentChannelDeliveryDetails[]` → each `{ contentUrl: url, managedContentChannelDetails: { id: channelId, name: channelName } }` |
+| `language` | `language` — present when language-variant search applied; use it per step 5 above |
+| `searchScore` | _(extra — hybrid-only relevance score; optional to surface)_ |
+
+**Omissions to account for:** if `language` is absent, omit the Language line for that item (and, if the call sent `searchLanguage`, tell the user the search couldn't be restricted to the requested language — see step 5).
+
+**Classifying channel type.** The hybrid response carries **no channel `type`** on its delivery entries, and because hybrid search ignores channel scope it can return an item delivered to a uiBundle channel. Fill in `managedContentChannelDetails.type` yourself so the public-channel-only URL rule in "Executing the search call(s)" above still holds:
+- An entry whose `channelId` matches any uiBundle `channelId` found in Step 1 (any `uiBundles/*/public/content-metadata.json` channel, or the named uiBundle's resolved channel) → `WEB_APP`. Its `url` is **never** surfaced as the Unauthenticated URL, and the render hand-off passes `contentKey` instead of a URL for it. Compare on the first 15 characters — Salesforce IDs appear in both 15- and 18-character forms.
+- Every other entry → treat as a public channel (`PUBLIC_UNAUTHENTICATED`), so its `url` is the Unauthenticated URL.
+
+A `WEB_APP`-classified entry is still a selectable channel option at disambiguation, exactly as in the keyword case — it just never produces a displayed URL.
+
+**Filter to the Step 2 content types.** The hybrid call takes no `contentTypeFqn`, so results can include types outside what Step 2 discovered. Keep only results whose `contentTypeFqn` is one of Step 2's FQN(s), so both sources answer the same question. If that filter removes every result from a non-empty response, don't report "no results" — tell the user which other content types came back and ask whether to show them.
+
+After mapping, the `managedContentChannelDeliveryDetails` array behaves identically to the keyword case (zero / one / many entries), so everything downstream — channel disambiguation, display, and the render hand-off — is reused as-is.
+
 ## Disambiguating channel at selection
 
 Reached at Step 3 point 5, only for a selected item whose (merged, per "Executing the search call(s)" above) `managedContentChannelDeliveryDetails` array has more than one entry. Build one option per entry, using that entry's `managedContentChannelDetails.name`, in the order the array returns them — not a fixed two-option choice. **Call `ask_followup_question` with these as its actual `question` and `options` parameters — never concatenate the channel list into the question string itself**, the same rule every other question in this skill follows:
@@ -111,7 +189,7 @@ I can render the following in the <uiBundle> app:
 
 ## Building the search query
 
-Keyword/taxonomy extraction rule: see `SKILL.md` Step 3 point 1 (the Media Route uses the same split — see `media-route.md` for media-specific examples). Additional worked examples for content:
+Keyword/taxonomy extraction rule: see `SKILL.md` Step 3 point 2 (the Media Route uses the same split — see `media-route.md` for media-specific examples). Additional worked examples for content:
 - "press release about our product launch" → keywords: launch, announcement, release, product launch; taxonomies: Launch, Announcement, News
 - "FAQs about password resets" → keywords: password, reset, login, account; taxonomies: _(empty — no descriptive/categorical terms)_
 

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