@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/nonprofit-volunteer-management-model-get/references/relationships.md

@@ -0,0 +1,175 @@
+# Relationship & Feature Map — Volunteer Management
+
+How the entities connect and combine into features. When a user expresses intent, find the feature
+here first, then drill into `entities.md`. Theme references (`Tn`) point at `themes.md`.
+
+## The backbone (structural spine)
+
+```text
+VolunteerInitiative  (optional top-level anchor; self-referential tree)
+   │  (optional links from JobPosition / Shift / Assignment)
+   ▼
+Position  (reusable TEMPLATE; carries PositionQualification)
+   │  JobPosition.Position  (lookup; JobPosition links UP — never the reverse; quals NOT copied)
+   ▼
+JobPosition  (concrete POSTING; optional Location; carries JobPositionQualification)
+   │  JobPositionShift.JobPosition  (required; deleting the JobPosition deletes its shifts)
+   ▼
+JobPositionShift  (concrete DATED occurrence; capacity; optional RecurrenceSchedule)
+   │  JobPositionAssignment.AssignedPositionShift  (optional)
+   ▼
+JobPositionAssignment  (a person doing it on a day; SOURCE OF TRUTH for hours)
+```
+
+**Rules that matter:**
+- **Shift and Assignment attach ONLY to JobPosition, never Position** (T15). Position alone cannot
+  be scheduled or assigned against. A JobPosition is required for scheduling/matching.
+- **Parentage is optional and mix-and-match** (T7, T21). A JPA may link to a Shift, a JobPosition,
+  a VolunteerInitiative, any mix, or none (standalone ad-hoc). VI may be absent entirely.
+- Position → JobPosition is **template → concrete posting** (T15): one template, many localized
+  postings, each able to add its own JobPositionQualifications.
+
+## Delete behaviour (informational — these skills never delete)
+
+| Deleting… | Effect |
+|---|---|
+| a Location | deletes its Addresses; blocked while a JobPosition uses it |
+| a Position | deletes its PositionQualifications; blocked while a JobPosition uses it |
+| a JobPosition | deletes its JobPositionShifts and JobPositionQualifications |
+| an OperatingHours | deletes its TimeSlots |
+| a Competency | blocked while a qualification uses it |
+
+## The authenticated boundary (who links to Account vs Contact)
+
+The single most important cross-cutting relationship rule (T2, T10, T16):
+
+| Entity | Account | Contact | Meaning |
+|---|---|---|---|
+| JobPositionAssignment | `AssignedAccount` (opt) | `AssignedContact` (opt) | guest creates Contact-only; Account attached on conversion. **Per-person (DGS) rollups require Account; VI rollups don't.** |
+| PersonLocationAvailability | required | optional | availability is authenticated-only (anti-bloat) |
+| PersonExamination | VM-added (opt) | required | credentials via portal want authenticated Account |
+| PersonCompetency | via polymorphic `Person` | via polymorphic `Person` | `Person` = {Account, Contact}; already had Account |
+| DonorGiftSummary | `Donor` (master-detail) | — | engagement history is Account-only |
+
+**Takeaway:** anything that persists a volunteer's own data trends toward requiring an authenticated
+Account. Guest (Contact-only) records are tolerated at signup but don't feed the per-person (DGS)
+rollups until an Account exists (VI rollups aggregate by initiative regardless).
+
+## Feature: Volunteer Matching (T9)
+
+Matches volunteers to opportunities on two axes — **held competency** and **availability**:
+
+```text
+HELD (supply)            REQUIRED (demand)                 WHERE/WHEN
+PersonCompetency ── vs ── PositionQualification ──┐        PersonLocationAvailability
+  → Competency            JobPositionQualification ├─       → Location ⇄ JobPosition.Location
+                            → Competency-only ──────┘        → OperatingHours → TimeSlot
+```
+
+- **Supply side:** **PersonCompetency only** — declared by the volunteer via Experience Cloud or set
+  by an internal user. The `Verification*` fields (`VerificationStatus`/`Date`/`Summary`) are
+  informational and **NOT used in matching** (verified vs merely claimed is not weighed).
+- **Demand side:** PositionQualification (template) + JobPositionQualification (extra, per posting).
+  Matching uses QualificationLevel on Competency qualifications. A Job Position's own qualifications
+  and its Position's qualifications are checked together, keeping the higher level per Competency.
+  Nothing is copied from the Position to the Job Position. `QualificationReferenceRecordId` can point
+  at a Competency or an Examination (T17); Examination qualifications are ignored, and a
+  qualification with no QualificationLevel is skipped.
+- **Examination is NOT a matching factor:** automated matching reads neither `PersonExamination` nor
+  Examination-typed requirements. Examination is for **manual/internal qualification** — a manager
+  reviews held credentials to qualify a volunteer (see `entities.md`).
+- **Where/when:** PLA matched via **JobPosition.Location** + **time-window containment** (a TimeSlot
+  must contain the shift window); with no time filter, matching falls back to Location-only.
+- **Level-aware:** the volunteer's `PersonCompetency.QualificationLevel` must be at or above the
+  required level. `ProficiencyLevel` is never read.
+
+## Feature: Shift capacity (T22) — counted, never enforced
+
+```text
+JobPositionAssignment.DoesCountTowardShiftCapacity = true   (default true; any status)
+        │  recounted on every JPA save and delete (NOT a rollup)
+        ▼
+JobPositionShift.PositionAssignmentCount  ──►  RemainingCapacity  [formula]
+```
+
+- `RemainingCapacity` = MAX(0, MaximumAttendeesCount − PositionAssignmentCount) when both are set and
+  MaximumAttendeesCount is above 0; otherwise blank.
+- Per-assignment boolean so waitlisted/observer assignments needn't be counted.
+- **Nothing blocks a signup when a shift is full.** A customer who wants a hard limit adds their own
+  validation rule.
+
+## Feature: Engagement rollups (T12, T13, T14)
+
+**Source of truth = JobPositionAssignment** (`ActualDuration` for hours).
+Two rollup targets, **both shipped empty — the customer builds and schedules a Data Processing Engine job**:
+
+- **Person-level → DonorGiftSummary** (4 VM fields): any JPA on the Person Account (NOT filtered by
+  VolunteerInitiative — the XML description saying otherwise is wrong, T13). Volunteer ≈ donor is why
+  it lives on the Fundraising entity (T14).
+- **Initiative-level → VolunteerInitiative** (6 fields): rolls up assignments for the initiative and
+  **up its self-referential tree** to parent initiatives. `TotalActiveVolunteerCount`/`AttendanceRate`
+  depend on customer-configured eligibility (which JPA `Status` values count).
+
+**ConstituentRole** is the companion flag: it marks *who is a volunteer* (`RoleType` = "Volunteer",
+a value that ships out of the box, T6) so the rollups are meaningful. ConstituentRole =
+the flag; the rollup fields = the totals.
+
+## Feature: Recurrence (T23)
+
+VM **decouples** RecurrenceSchedule from the shared recurrence engine other clouds use. In VM it is
+**purely informational** — viewing a JobPositionShift, you can see it's part of a series and what the
+series looks like. VM ships a feature that, on creating a recurring schedule, generates the
+RecurrenceSchedule record AND **materializes every JobPositionShift upfront** (time-bounded, capped).
+All shift rows exist in the DB immediately; nothing appears dynamically later.
+
+## Feature: Approval + Stage Management (T18, T24, T25, T26)
+
+```text
+Position.IsInternalApprovalRequired = true   (inert flag on the template)
+        │  customer wires Salesforce Approvals to it
+        ▼
+Salesforce Approvals runs on a JobPositionAssignment
+        │  on approval, Stage Management advances…
+        ▼
+JobPositionAssignment.Status  (e.g. "Awaiting Approval" → "Upcoming")
+```
+
+- VI, Position, JobPosition, JobPositionShift and JobPositionAssignment each have their own `Status`
+  picklist with values that ship out of the box (see the picklist table in `entities.md`) —
+  **independent lifecycles** (T24). No cross-entity status propagation (closing a JobPosition does not auto-close its Shifts; a JPA
+  "Complete" doesn't auto-feed VI — that's the Data Processing Engine job's work).
+- **Stage Management** (a built-in platform feature) drives automations as an enum progresses
+  through stages (T25). The Status field alone is just a picklist; registering it with Stage
+  Management makes it a governed lifecycle.
+- The Position approval flag ultimately resolves on **JPA.Status** (T26).
+- **No Status is "primary."** structure-generate and records-create treat each lifecycle separately.
+
+## Feature: Benefit bridge (T19, T20)
+
+```text
+PositionBenefit  (requires VM && Benefit Management — compound AND gating)
+   Position (master-detail)  ──►  Benefit  (OUT OF SCOPE — external dependency)
+```
+
+Volunteers provide a service that beneficiaries receive **as a Benefit**. Attached at the Position
+(template) level since all its JobPositions provide the same service. Benefit itself is Program
+Management — treat as an external dependency, never model it.
+
+## Quick intent → entity lookup
+
+| User intent | Entities / fields |
+|---|---|
+| "Mark someone as a volunteer" | ConstituentRole (`RoleType`="Volunteer", ships out of the box) |
+| "Track completed volunteer hours" | JobPositionAssignment.`ActualDuration` → DonorGiftSummary/`VolunteerInitiative` rollups (build a Data Processing Engine job) |
+| "Let volunteers say when/where they're free" | PersonLocationAvailability (+ Location, OperatingHours, TimeSlot) |
+| "Record a volunteer's skills / credentials" | PersonCompetency (matched vs Competency qualifications) / PersonExamination (credentials; manual qualification only, not matched) |
+| "Record a cause or interest a volunteer cares about" | Not PersonCompetency (it feeds matching). Use a customer-defined interest or preference field on a related record |
+| "Define a reusable job" | Position (+ PositionQualification) |
+| "Post that job (optionally at a location)" | JobPosition (+ JobPositionQualification for extra local reqs) |
+| "Schedule a specific dated slot" | JobPositionShift (+ capacity fields) |
+| "Sign someone up" | JobPositionAssignment (link to Shift/JobPosition/VI as desired) |
+| "Cap a shift at N people" | JobPositionShift.`MaximumAttendeesCount` + JPA.`DoesCountTowardShiftCapacity` — counted, never enforced; a hard limit needs a customer validation rule |
+| "Require approval before signup" | Position.`IsInternalApprovalRequired` + Salesforce Approvals + JPA.`Status`/Stage Management |
+| "Organize activities under a campaign/initiative" | VolunteerInitiative (self-referential tree) |
+| "Volunteers deliver a benefit to those we serve" | PositionBenefit (needs VM && Benefit Management) |
+| "Recurring shifts" | RecurrenceSchedule (informational) + a shipped feature pre-generates all Shifts |

package/skills/nonprofit-volunteer-management-model-get/references/themes.md

@@ -0,0 +1,143 @@
+# Design Principles (Themes) — Volunteer Management
+
+The recurring principles that explain *why* the model is shaped the way it is. `entities.md` and
+`relationships.md` cite these by number. Read these to reason about parts of the model this skill
+doesn't spell out explicitly — the principles generalize.
+
+## Identity & the authenticated boundary
+
+**T1 — The volunteer is a Person Account.** Person Accounts must be enabled (hard prerequisite).
+The "Business Account" box in the diagram is just how Salesforce renders Person Accounts — ignore
+that variant.
+
+**T2 — The authenticated boundary drives the Contact-vs-Account split.** Contact-only = guest /
+pre-account (public Experience Cloud signup). Person Account = authenticated volunteer after
+creation/conversion. Entities choose Contact vs Account by whether the flow can be unauthenticated.
+Assignment supports both (guest → convert); history/rollup entities require Account.
+
+**T3 — Permission tiers mirror the boundary.** `userHasVolunteerManagement` = internal staff;
+`userHasVolunteerManagementCmtyAccess` = authenticated community volunteer;
+`userHasGuestVolunteerManagementCmtyAccess` = unauthenticated guest; `orgHasVolunteerManagement` =
+org-level enablement (API access, related lists). Map any gate to these actor types.
+
+**T10 — Guest Contact bloat is *why* the boundary exists.** Guest forms can create the same person's
+Contact repeatedly with no dedup. To avoid record bloat, entities that persist a volunteer's own
+data (availability, credentials, history) require an authenticated Account. This is the mechanical
+reason behind T2.
+
+**T16 — VM insists on Person Account at the portal boundary.** Where VM persists volunteer-owned
+records via Experience Cloud (PersonExamination, PLA), it requires an authenticated Account — even
+adding an Account link to a borrowed entity that only had Contact (PersonExamination). PersonCompetency
+needed nothing because its polymorphic `Person` already included Account.
+
+## Reuse philosophy
+
+**T4 — Account is a "hero" entity.** Deliberately hard to extend with fields, so product data hangs
+off related/extension entities rather than new Account/Contact fields. This explains the whole
+"borrowed entity + related entity" shape of the model. VM adds zero fields to Account/Contact.
+
+**T14 — Volunteer ≈ Donor.** VM assumes a volunteer is likely also a donor, so volunteer engagement
+data is co-located on the Fundraising DonorGiftSummary rather than a new entity. Reinforces T4.
+
+**T11 — "Generic entity, single current customer."** Some native-looking entities (PLA) were built
+generic so any product could adopt them; VM is the only current customer. A UsageType/discriminator
+field keeps products' records from colliding — set it to the VM value.
+
+**T17 — Polymorphic scopes are deliberately narrow.** QualificationReferenceRecord supports
+{Competency, Examination} only — the polymorphic lookup permits exactly those two targets. Reference
+only the domains actually in a polymorphic set; do not assume other qualification types are targetable.
+
+**T20 — Compound (AND) gating signals a cross-product bridge.** Most entities use OR gating (any of
+several clouds can access — plain reuse). PositionBenefit uses AND (`VM && BenefitManagement`) — a
+deliberate bridge requiring both products. When you see `&&` across clouds, it's a cross-product
+feature, not reuse.
+
+## Structural patterns
+
+**T5 — Standing/informational vs operational/per-occurrence.** The model separates "who someone IS"
+(ConstituentRole — is-a-volunteer, active/inactive, dates) from "what someone DID"
+(JobPositionAssignment — a specific job, place, date; one record per occurrence).
+
+**T7 — Optional / flexible parentage.** Many links are intentionally optional and mix-and-match
+rather than an enforced hierarchy (e.g. JPA → Shift / JobPosition / VolunteerInitiative, any mix or
+none). The model favors flexibility; structure-generate helps the user decide the shape.
+
+**T15 — Position → JobPosition template model is the backbone.** Position = reusable template
+(+ PositionQualifications); JobPosition = concrete posting (optionally at a Location) that
+**references** the template via a lookup and can add JobPositionQualifications. A Job Position's own
+qualifications and its Position's qualifications are checked together, keeping the higher level per
+Competency. Nothing is copied from the Position to the Job Position (see `entities.md` → JobPosition). Shift &
+Assignment attach ONLY to JobPosition. One template → many localized postings with location-specific
+extra requirements.
+
+**T21 — VolunteerInitiative = optional top-level parent.** VI is the intended parent of
+JobPosition/Shift/Assignment and is self-referential (a hierarchical tree), but linkage is
+deliberately optional — ad-hoc work with no VI is allowed. VI is the organizing anchor when you want
+one, not a required root.
+
+## "Mechanism shipped, enforcement/config is the customer's"
+
+**T6 — Most picklists ship with values.** Most of VM's picklists have values out of the box —
+including `ConstituentRole.RoleType = "Volunteer"` (see the picklist table in `entities.md`).
+Position Type, Sensitivity and Schedule Type and Competency Category ship empty. When a needed
+value already ships, tell the user it's there; otherwise an admin can add it. Only the platform
+picklists (TimeZone, TimeSlot DayOfWeek and Type) can't take a new value.
+
+**T12 — Some rollups/features are NOT shipped populated.** DonorGiftSummary's 4 fields and
+VolunteerInitiative's 6 fields have no Data Processing Engine definition out of the box — the
+customer creates and schedules one. Fields exist empty until then. Real-time isn't feasible at this volume.
+
+**T18 — Fields as hooks into other platform features.** Some VM fields are inert flags meant to be
+wired into existing features. `Position.IsInternalApprovalRequired` → Salesforce Approvals. The
+`Status` picklists → Stage Management. These need configuration to do anything.
+
+**T22 — Capacity is counted, never enforced.** A hook recounts `JobPositionShift.PositionAssignmentCount`
+on every JPA save and delete (JPAs with `DoesCountTowardShiftCapacity = true`); `RemainingCapacity` is
+a formula. Nothing blocks a signup when a shift is full — a customer who wants a hard limit adds a
+validation rule.
+
+**T23 — VM decouples RecurrenceSchedule and pre-generates all shifts.** Unlike other products that
+use the shared recurrence engine for dynamic generation, VM treats RecurrenceSchedule as purely
+informational and ships a feature that materializes every JobPositionShift upfront (time-bounded,
+capped). Recurrence is a generation-time convenience, not runtime behavior.
+
+**T24 — The Status lifecycles are independent.** VI / Position / JobPosition / JobPositionShift /
+JobPositionAssignment each have their own Status picklist with values that ship out of the box (see
+the picklist table in `entities.md`). There is **no cross-entity propagation** (closing a JobPosition
+does not auto-close its Shifts; a JPA "Complete" doesn't auto-feed VI — that's the Data Processing
+Engine job's work). No Status is "primary" — treat each as separate.
+
+**T25 — Stage Management is the platform feature the Status picklists plug into.** It enables
+automations as a Status progresses through stages. A Status field alone is just a picklist; registering it with
+Stage Management makes it a governed lifecycle. VM ships the field as the hook.
+
+**T26 — The approval flag ultimately plays out on JPA.Status.** `Position.IsInternalApprovalRequired`
+(flag on the template) → Salesforce Approvals (customer-wired) → JPA.Status advanced by Stage
+Management (e.g. "Awaiting Approval" → "Upcoming"). VM ships the flag and the Status values; the
+customer still wires the Approvals process and any Stage Management automation.
+
+## Trust intent over doc text
+
+**T13 — Field description text can be misleading.** Capture intended behavior, and note corrections
+where shipped text misleads. Known case: DonorGiftSummary rollup fields say "related to a volunteer
+initiative" — the real intent is "any JPA related to the Person Account" (VolunteerInitiative is NOT
+a filter).
+
+## Features (composite themes)
+
+**T8 — Deprecated (was: Corporate / group volunteering).** Removed — VM has no supported solution
+for corporate/group volunteering yet. Number retained to keep existing theme references stable; do
+not reuse it. Do not advise agents to model corporate/group volunteering (e.g. via
+`ConstituentRole.Institution`).
+
+**T9 — Volunteer Matching.** Matches volunteers to opportunities on two axes: **held competency**
+(PersonCompetency vs Position/JobPosition Qualification requirements) and **availability**
+(PersonLocationAvailability ↔ JobPosition.Location + TimeSlot time-window containment). Matching
+uses QualificationLevel on Competency qualifications; ProficiencyLevel is never read. A Job
+Position's own qualifications and its Position's qualifications are checked together, keeping the
+higher level per Competency. **Competency-only:** matching reads neither PersonExamination nor
+Examination qualifications. Examination is for manual/internal qualification.
+
+**T19 — Volunteering ↔ Benefit Management bridge.** Volunteers provide a service beneficiaries
+receive as a Benefit. PositionBenefit is the bridge (Position → Benefit), requiring both clouds.
+Benefit itself is out-of-scope (Program Management) — external dependency.

package/skills/nonprofit-volunteer-management-records-create/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: nonprofit-volunteer-management-records-create
+description: "Use this skill to write Salesforce Nonprofit Cloud Volunteer Management (VM) records to an org once the user knows what to create, from a confirmed plan or a list of records: it reuses existing records by their Ids instead of duplicating them, asks for any missing required values, shows each object's records table for approval, inserts the records in dependency order, reads each write back, recovers from write errors, and reports every created Id. TRIGGER when a user wants to create, insert, import, or write VM records. DO NOT TRIGGER to decide what a program needs (use nonprofit-volunteer-management-structure-generate), to explain what a VM object or field is for (use nonprofit-volunteer-management-model-get), to enable Volunteer Management in an org, for per-person records (JobPositionAssignment, PersonLocationAvailability, PersonCompetency / PersonExamination, ConstituentRole), or for NPSP / Volunteers for Salesforce (V4S), which is unsupported."
+metadata:
+  version: "1.2"
+  domains: ["Nonprofit"]
+  relatedSkills:
+    - "nonprofit-volunteer-management-model-get"
+    - "nonprofit-volunteer-management-structure-generate"
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck: "(OrgPermissions.VolunteerManagement) && (OrgPreferences.VolunteerManagementEnabled)"
+---
+
+# Nonprofit Cloud Volunteer Management — Record Creation
+
+This skill writes Volunteer Management records to an org: a Volunteer Initiative and the Locations, Positions, Job Positions, qualifications and Job Position Shifts under it. It checks the org for records it can reuse, fills each field from `references/field-guide.md`, shows the user one records table per object, and writes that object only after the user confirms its table. **Open every run by telling the user that this skill reads and writes their org, and that nothing is read or written without their yes.**
+
+## Hard rules
+
+- **Never delete records.** No delete, rollback or cleanup of any kind. If a write fails part-way, report what was created and what wasn't; never undo it.
+- **Never act on NPSP or Volunteers for Salesforce (V4S).** That legacy package is unsupported here. Say so and stop.
+- **No acronyms or internal labels in what the user sees.** Write out Volunteer Initiative, Job Position, Job Position Shift, Job Position Assignment, Position Qualification, Job Position Qualification, Data Processing Engine, and "out of the box". Never show internal step or section labels.
+- **Writes need a yes per object.** Nothing is written until the user confirms that object's records table.
+
+## Mechanism
+
+Org calls go through the connection the session has: the headless-360 tools (`dispatch_readonly` for reads, `dispatch` for writes) or an authenticated Salesforce CLI. Both return the same results at API v67.0. Tell the user which one is in use. If neither is connected, stop and ask the user to connect one; never guess an org result. The exact call for each step, in both forms, is in `references/mcp-invocation.md`.
+
+## Scope
+
+- **In scope:** Volunteer Initiative (including child initiatives), Location and its Address, Competency, Examination, Position, Position Qualification, Job Position, Job Position Qualification, Job Position Shift; Operating Hours and Time Slots only when the user asks for them. Reusing existing records, filling fields, detecting required custom fields, writing in dependency order, and recovering from write errors.
+- **Out of scope:** deciding what to build (`nonprofit-volunteer-management-structure-generate`); explaining what an object or field means (`nonprofit-volunteer-management-model-get`); turning Volunteer Management on; any per-person record — volunteer sign-ups and assignments, a volunteer's availability, a person's qualifications, marking a person as a volunteer, the person or household itself. The full list is in `references/field-guide.md` "Out of scope".
+
+## Required inputs
+
+- **The records to create.** Chained: the plan from structure-generate — its summary table, the Id of each reused record, the schedule details, the outstanding inputs and the `Reuse-check:` line. Standalone: ask the user what to create.
+- **Field values.** `references/field-guide.md` is the authority for every standard field: API name, required flag, tier, default and must-ask rules. Ask for each outstanding input from the plan when its object comes up.
+- **Defaults:** propose Status `Upcoming` on a new Volunteer Initiative, Position, Job Position and Job Position Shift — offer Status's live values, and if none fits, offer to add one (step 6). Every other default is in the field guide. Location Type has no default and is always asked.
+
+## Workflow
+
+1. **Open and pick the mode.** Give the opening notice above. Chained: work from the handed-off plan and don't re-interview. Standalone: gather the records from the user.
+2. **Ask for the read consent, once.** Say what you'll read and why: the Volunteer Management check, the reuse checks, the existing-shift check, and the object descriptions used for required custom fields and live picklist values. Declining means existing records can't be checked, so duplicates may be created, and required custom fields surface only as write errors. If declined, proceed from the plan without reading: every record not already marked Reuse is New, and picklist values are the user's; one the org doesn't accept surfaces as a write error.
+3. **Check that Volunteer Management is on**, once, after the user agrees to the org read (calls in `references/mcp-invocation.md`):
+   1. Read the org preference `VolunteerManagementEnabled`. `true` → on. `false` or 404 → off: stop and tell the user an admin turns it on in Setup → Volunteer Management Settings. 403 → the user has no access to org settings: stop and say so.
+   2. Describe `VolunteerInitiative`. 200 → the user can see the Volunteer Management objects. Any error → stop and tell the user they need the Manage Volunteer Data permission set. Don't look up permission-set assignments beforehand.
+4. **Reuse checks, by the plan's `Reuse-check:` line.**
+   - `RESOLVED` → the plan's Reuse/New mapping is authoritative. Use its reused Ids as-is and don't re-run the reuse checks.
+   - `DECLINED` → run the reuse checks for every record the plan marks New.
+   - Missing or unrecognized line, or standalone → run the reuse checks for every planned record.
+
+   One bounded query per object, filtered to the planned names (never the whole object). Match a Job Position on Name + Volunteer Initiative, Operating Hours on Time Zone + its set of Time Slot windows (never the name), everything else on Name. Escape an apostrophe in a name with a backslash (`O\'Brien`); doubling it fails. Query only fields the field guide documents. For a reused Location, read its Visitor Address: if it has one, don't create another.
+5. **Existing-shift check — on every plan, including `RESOLVED`.** For each Job Position that is reused, query its shifts by that Job Position's Id and the series' date range; never by name or Position. If N of the M planned shifts already exist, stop and ask: "N of M shifts already exist (dates X–Y). Create only the missing ones, create all M (duplicates), or cancel?" On "only the missing ones", pass the existing shifts to `scripts/expand-series.py` as `excludeExisting`. A new Job Position has no shifts to check.
+6. **Read the object descriptions** for each object you'll write: find required custom fields (custom, createable, not nillable, not defaulted on create) and the live picklist values. Never describe an object to learn its standard fields — the field guide is the source for those — but when a description is in hand and differs from the field guide (a renamed label, a picklist value), the description wins. A required custom field becomes a `needs-input` column on that object's table.
+   - **Platform picklists** (Time Zone, Time Slot Day of Week and Type): offer only the live values. A value outside them is rejected before the write, never sent.
+   - **Every other picklist:** offer the live values. If none fits, ask whether to add one; on a separate yes, get it added before the write. On headless-360 the user adds it in Setup and you give them the exact path; on the Salesforce CLI you add it for them (`references/mcp-invocation.md`). Use it only once a fresh describe lists it; a value that isn't in the list yet is rejected on write.
+7. **Summarize, then review one object at a time.** Lead with the insert summary in `references/review-format.md`: what will be written, Reuse ("Name · object") and New counts per object, how the records fit together, and the write order. Ask the fill mode: prefill everything, or generate together. Then, for each object in write order, show its field guide and its records table. **Render every records table with `scripts/render-review-table.py`, never by hand** — it keeps every value under its own column. Invite edits and re-render. Confirming an object's table is the yes to write it; there is no second confirm.
+8. **Write each confirmed object, parents first.** Order: Volunteer Initiative (parents, then child initiatives) → Location → its Address → back-fill the Location's Visitor Address → Competency / Examination → Position → Position Qualification → Job Position → Job Position Qualification → Operating Hours → Time Slot (only on request) → Job Position Shift. Skip objects the plan doesn't use.
+   - Several records of one object go in one tree call (all-or-nothing, up to 200 records). Over 200, split into batches.
+   - A parent written in an earlier call is referenced by its literal Id. A `@refId` reference works only inside the same call.
+   - A child Volunteer Initiative goes in a second call after its parent, with the parent's literal Id.
+   - A new onsite Location gets its Address (street, city, state, postal code and country from the user; Location Type and Time Zone copied from the Location), then the Location's Visitor Address is set to the new Address. A virtual Location, or a reused one that already has an Address, gets none.
+   - Feed returned Ids forward to children; don't re-query records you just created.
+   - Read each write back to confirm it.
+   - **Shift series:** build the `scripts/expand-series.py` spec from the plan's schedule details — days and windows (`windowsByDay` when windows differ by day), start date, end date or `count`, time zone, volunteers per shift, the confirmed Status, and `excludeExisting` from step 5. A monthly or irregular schedule goes in as `oneOffDates` with the dates the user confirms. Tell the user the series ends there; later shifts are added in a later run.
+9. **Recover from errors.** Show the error, propose a fix grounded in the error message and the object description, and re-send only the records that weren't created. If a write fails part-way, say which records exist and which don't; never undo.
+10. **Final report.** One table of every record this run wrote or reused (object, name, Id, Reuse or New) and the planned-versus-written count, in the layout in `references/review-format.md`. For a shift series, state the dates it covers.
+
+## Rules
+
+| Constraint | Rationale |
+|-----------|-----------|
+| One read consent; one write consent per object, given on that object's records table | Approving a read is not approval to write. A partial decline is treated as declined. |
+| Reuse existing records; never duplicate | Every planned record gets a reuse decision before it's written; shifts of a reused Job Position are checked on every run. |
+| Every org query is bounded to the plan | Filter on the planned names; never read a whole object. The query is a duplicate check, not a listing. |
+| Never write tier 4 or 5 fields | They are system-managed, auto-numbered, formulas or owned by another feature; writing them errors or is overwritten. |
+| Never create a Recurrence Schedule | Volunteer Management's own recurrence feature owns it; this skill writes one Job Position Shift per occurrence. |
+| Every shift series has an end date or a count | Each shift is its own record; an open-ended series would never stop. |
+| Operating Hours and Time Slots only when the user asks | Nothing links them to a Location or Job Position; they are used only for volunteer availability matching. |
+| Never build a series or a records table by hand | `scripts/expand-series.py` and `scripts/render-review-table.py` are reviewed and tested; hand-built dates and tables shift values. |
+| Show names, not Ids or API names, before the final report | The user reviews records in plain language; Ids appear only in the final report. |
+
+## Gotchas
+
+| Issue | What to do |
+|-------|------------|
+| Location and Address point at each other | Write the Location, then the Address with its Parent set to the Location, then update the Location's Visitor Address. |
+| Operating Hours and Time Slots | Write the Operating Hours first, then its Time Slots in a second call with the literal Id. |
+| Child Volunteer Initiative in the same call as its parent | A self-reference fails with `MALFORMED_ID`; write parents first, then children with the literal parent Id. |
+| Job Position Shift dates and times | Separate StartDate, EndDate, StartTime, EndTime and TimeZone fields; there is no combined date-time field. |
+| Qualifications | Matching uses QualificationLevel on Competency qualifications. A Job Position's own qualifications and its Position's qualifications are checked together, keeping the higher level per Competency. Nothing is copied from the Position to the Job Position. |
+| Shift capacity | Counted, never enforced: nothing blocks a signup when a shift is full. |
+| A required field the description didn't show (a validation rule) | It surfaces as a write error; handle it in step 9. |
+
+## Output expectations
+
+- The confirmed Volunteer Management records written to the org in dependency order, or reused.
+- A final report of every record written or reused, with its Id, and the planned-versus-written count.
+- Keep every message compact, in the layout in `references/review-format.md`: one field guide and one records table per object, one row per record (a shift series is one row; past 10 series, one row per shared schedule), and say each point once. Don't restate a table in prose, add sections the layout doesn't have, or show a write payload per record; if the user asks to see the payload, show one representative example per object.
+
+## Cross-skill integration
+
+| When | Do |
+|------|----|
+| The user doesn't know what to build | Defer to `nonprofit-volunteer-management-structure-generate`; it produces the plan this skill writes. |
+| The user asks what an object or field means | Defer to `nonprofit-volunteer-management-model-get`. |
+| Chained from structure-generate | Work from the handed-off plan. Handle its `Reuse-check:` line as in step 4, and run the existing-shift check in step 5 regardless. |
+
+## Reference file index
+
+| File | When to read |
+|------|-------------|
+| `references/mcp-invocation.md` | Steps 3–6, 8 — the exact read and write calls for headless-360 and the Salesforce CLI, the Volunteer Management check, apostrophe escaping, adding a picklist value. |
+| `references/field-guide.md` | Steps 4, 6–8 — every object's fields, API names, tiers, defaults, must-ask rules and limits. |
+| `references/review-format.md` | Steps 7 and 10 — the insert summary, the per-object review, the origin tags and the final report. |
+| `scripts/render-review-table.py` | Step 7 — renders each records table from JSON (field → value + origin tag). Spec in its docstring. Tests: `scripts/tests/test_render_review_table.py`. |
+| `scripts/expand-series.py` | Step 8 — expands a shift or time-slot series into tree-call records: weekly windows or per-day windows, date ranges, one-off dates, `excludeDates`, `count`, `excludeExisting`. Spec in its docstring. Tests: `scripts/tests/test_expand_series.py`. |