1. Read the config JSON end-to-end from the exact path the user gave (default

   ./post-copy-config.json

   ). Every entry must have all five keys (

   ConfigurationName

   ,

   Label

   ,

   Fields

   ,

   IsActive

   ,

   ExecutionOrder

   ). If any entry is malformed, abort and surface the file path + entry index — do not partially apply. Do not invent entries. If the file is missing, stop and ask; never fabricate a plan against synthetic labels.
2. For each distinct

   ConfigurationName

   in the config, run the derivation + describe-verify step (below) before planning any PATCH. An entry whose API cannot be verified must never appear as a planned PATCH — it is rejected up front.
3. Confirm the target org alias with the user unless they supplied one explicitly. This skill mutates a live org — writing to the wrong org (e.g., a production alias set as default) is the most expensive failure mode.

ConfigurationName

sf api request rest \
  "/services/data/v<apiVersion>/tooling/sobjects/<Candidate>/describe/"

• HTTP 200 (the sobject exists on this org's Tooling API), AND
• The describe response's

  fields

  array contains a field named

  Metadata

  (compound field — this is what PATCH writes through).

API_NOT_IDENTIFIED

/tmp/entry-<Slug>-lookup.json ID=$(jq -r '.result.records[0].Id // empty' /tmp/entry-<Slug>-lookup.json)

Pick `<UniqueFilter>` based on the queryable fields shown in the
describe response from Step B. If the row contains a `FullName` field,
SOQL usually rejects a direct `FullName = ...` filter — filter by
whichever direct column the describe surfaces (e.g.
`EntityDefinition.QualifiedApiName`, `DeveloperName`, `SiteName`) and
apply the `FullName` match client-side (`jq -r
'.result.records[] | select(.FullName == "<Object>.<Label>") | .Id'`).

Outcomes:

- Zero rows → `NOT_FOUND` (never fall back to insert).
- Multiple rows after client-side filtering → `AMBIGUOUS` (surface
  all Ids in the summary and skip; a wrong Id is worse than no Id).
- Exactly one row → proceed to Step D.

Metadata

"<preserved-from-GET>"

<Id>

/tmp/entry-<Id>-meta.json

1. GET current

   Metadata

   →

   /tmp/entry-<Id>-meta.json

   .
2. Resolve the mutation key — for each

   Fields.<Xxx>

   , run

   node scripts/map-metadata-key.mjs "<ConfigurationName>" "<ConfigFieldName>" /tmp/entry-<Id>-meta.json

   . On

   {"status":"OK","key":...}

   use the returned key. On

   {"status":"FIELD_MAP_UNKNOWN",...}

   mark the entry and skip.
3. PATCH — heredoc-build

   /tmp/entry-<Id>-mutation.json

   , merge with

   jq --slurpfile m /tmp/entry-<Id>-mutation.json '. + $m[0] | {Metadata: .}' /tmp/entry-<Id>-meta.json > /tmp/entry-<Id>-patch.json

   (preserves JSON types), PATCH with

   -b @/tmp/entry-<Id>-patch.json

   , capture the response body to

   /tmp/entry-<Id>-response.json

   . Full bash in

   references/api_endpoints.md

   §Step D. Never use

   --arg

   (stringifies booleans/numbers, breaks on special chars). Wrap the PATCH in

   for attempt in 1 2; do <cmd> && break; done

   — retry once on shell/jq quoting failure (non-zero exit before the HTTP call goes out).
4. Classify —

   node scripts/classify-patch-result.mjs "<httpCode>" /tmp/entry-<Id>-response.json

   . Exit 0 →

   SUCCESS

   ; exit 2 →

   FAILED

   (parsed error on stdout). 204 with a non-empty body is

   FAILED

   .

• If the mutated field is a direct-queryable SOQL column on the sobject (rare — most

  Metadata

  -writable fields are not), a SELECT by Id is enough.
• Otherwise GET the record and inspect the corresponding key inside

  .Metadata

  .

FAILED_VERIFY

• IsActive: true

  → apply the PATCH as described in Steps A–E.

• IsActive: false

  → do not PATCH. Record

  SKIPPED_INACTIVE

  for the entry and add a bullet under Follow-ups in the summary file listing the entry's

  ConfigurationName

  +

  Label

  so the customer notices that a config-declared inactive record was left untouched on the target org.

IsActive: false

• Method:

  PATCH

• Path:

  /services/data/v<apiVersion>/tooling/sobjects/<VerifiedSobject>/<Id>

• Body:

  <JSON — the FULL merged Metadata object: every existing key from the Step D-1 GET, overlaid with the mutated keys from the config. Preserved keys with verbose or org-specific values may appear as "<preserved-from-GET>" placeholder strings, but every key must be present. NEVER emit a minimal body containing only the mutated keys.>

• <bullet per SKIPPED_INACTIVE / API_NOT_IDENTIFIED / AMBIGUOUS / FIELD_MAP_UNKNOWN / NOT_FOUND entry>

Column semantics: `Object` = the entry's `Fields.Object` if present,
`—` otherwise. `Sobject` = the Step A resolved sobject. `Describe` =
the Step B describe HTTP status (`200` for verified, `404` for
`API_NOT_IDENTIFIED`) — mandatory so skipped Step Bs are visible at a
glance. Outcome vocabulary: `SUCCESS`, `NOT_FOUND`, `AMBIGUOUS`,
`API_NOT_IDENTIFIED`, `FIELD_MAP_UNKNOWN`, `FAILED`, `FAILED_VERIFY`,
`SKIPPED_INACTIVE`, `SKIPPED`, `DRY_RUN`, `DELETE_NOT_SUPPORTED`,
`NOT_ATTEMPTED`.

**Scripts are internal.** The `plan-phases.mjs`, `map-metadata-key.mjs`,
`classify-patch-result.mjs`, `resolve-target-org.mjs` invocations are
implementation detail — do **not** inline their raw stdout, JSON
output, or "I ran node …" narration into the summary Markdown or
the printed response. Consume the JSON, use the returned values, and
render the summary in the exact shape above.

• In scope: Reading a post-copy config JSON (the shape produced by

  automation-sandbox-post-copy-config-generate

  ), grouping entries into

  ExecutionOrder

  phases, deriving+verifying the Tooling API sobject for each entry, resolving Ids via SOQL-over-REST, PATCHing via compound

  Metadata

  , and reporting per-entry outcomes.
• Out of scope: Generating the config JSON from an SOP (delegate to

  automation-sandbox-post-copy-config-generate

  ); deploying metadata XML; running the Async Task Framework (ATF) orchestrator itself (that is the platform-side Java implementation); inventing API paths for

  ConfigurationName

  values whose describe probe fails (surface as

  API_NOT_IDENTIFIED

  and stop).

--dry-run

• Config file path: Path to the JSON produced by

  automation-sandbox-post-copy-config-generate

  (default:

  ./post-copy-config.json

  in the current directory). If the file does not exist, stop and ask.
• Target org alias / username: The

  sf

  CLI alias or username of the target sandbox. Never assume the default org — always confirm. If the user has not supplied one, list available orgs with

  sf org list --json

  and ask which to use.
• Dry-run flag (optional, default

  false

  ): Semantics — reads are ALLOWED, writes are FORBIDDEN. Dry-run means the run produces no mutation on the target org; it does NOT mean "no network calls". You MUST still execute every read against the org: the describe probe (Step B,

  GET

  ), the SOQL Id lookup (Step C,

  sf data query

  ), and the record fetch (Step D-1,

  GET

  ) — because the plan's "would-be PATCH body" can only be accurate if the agent has read the current

  Metadata

  block from the live record. The ONLY skipped calls are the writes: Step D-3 (

  PATCH

  ) and Step E (post-PATCH verification). Never fabricate the current Metadata; never emit a body containing invented keys. If a read fails (401, 404,

  NamedOrgNotFoundError

  ), surface the error and stop — do not fall back to a from-memory plan. Use dry-run on the first pass unless the user has explicitly asked to apply.
• Continue-on-error (optional, default

  true

  ): When true, a failing entry does not abort the phase — the remaining entries in the phase still execute, and the failure is reported in the summary. When false, a failure aborts execution mid-phase.

sf

1. Read and validate the config JSON — load the file with the Read tool. Every entry must be a JSON object with the five top-level keys (

   ConfigurationName

   ,

   Label

   ,

   Fields

   ,

   IsActive

   ,

   ExecutionOrder

   ). Malformed entries are a hard stop.
2. Resolve the target org and API version — run

   sf org display --json

   . Parse the JSON to confirm the alias resolves and to capture

   result.apiVersion

   (e.g.

   62.0

   ). Do not print the raw JSON — it contains the access token.
3. Plan phases — run

   node scripts/plan-phases.mjs <config.json>

   and iterate its

   phases[]

   output. See

   references/execution_phasing.md

   for the concurrency cap.
4. Per-entry describe-verify pass — for each distinct

   ConfigurationName

   , run Step A + Step B once and cache the verified sobject. Any

   ConfigurationName

   failing Step B marks every entry with that name as

   API_NOT_IDENTIFIED

   .
5. Per-entry apply pass — for each entry inside each phase:
   • Entries pre-marked

     SKIP_INACTIVE

     by plan-phases → record

     SKIPPED_INACTIVE

     , add a Follow-ups bullet, continue.
   • Else run Step C (resolve Id), then Step D (GET+mutate+PATCH), then Step E (verify). If

     --dry-run

     is true, still run Step C and D-1/D-2 so the printed plan reflects the real merged payload — skip only D-3 (the PATCH) and Step E, then record

     DRY_RUN

     .
6. Between phases — wait for every entry in the current phase to complete before starting the next.
7. Write the summary file to disk — the final deliverable is a Markdown file at

   ./post-copy-<mode>-summary.md

   , following the shape in the "Canonical output shape" section. Also print it to the user. Never write access tokens or full

   sf org display

   output. If a URL contains embedded credentials, mask them in the summary (

   https://user:***@host/...

   ); the actual PATCH body carries the verbatim URL.