@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/education-cloud-multi-campus-configure/examples/output_examples.md

@@ -0,0 +1,54 @@
+# Example Output Structures
+
+## Step 6 — pre-write preview templates
+
+New setup:
+```text
+About to create:
+• [N] Account records across [M] levels
+  - System: 1
+  - [Level 1 name]: [count]
+  ...
+• [N] BusinessProfile records (1 per new Account)
+• RecordType: [recordTypeDeveloperName]
+```
+
+Update/reconcile — show the delta explicitly:
+```text
+Reconcile plan (update mode):
+• Create: [C] new Accounts  ([list level: count])
+• Rename: [R] Accounts      ([old → new])
+• Move:   [V] Accounts      ([node → new parent])
+• Unchanged (reused): [U] Accounts
+• Extra in org, NOT touched: [E]  ([list])
+• BusinessProfiles to create: [only for new Accounts missing one]
+```
+
+## Step 10 — completion report
+
+Example output structure (new setup):
+```text
+Institutional hierarchy created successfully.
+
+Created:
+- 1 System Account (Riverside Community College System)
+- 3 Campus Accounts (Main, North, South)
+- 7 College Accounts (across all campuses)
+- 12 Department Accounts (across all colleges)
+- 23 Business Profiles (linked to all accounts)
+
+Total: 23 Account records with proper parent-child relationships
+System (root) Account Id: 001XXXXXXXXXXXXXXX (use this to update later)
+```
+
+Example output structure (update/reconcile):
+```text
+Hierarchy reconciled.
+
+- Created:   2 Accounts (Department: Data Science, Department: Robotics)
+- Renamed:   1 Account  (English Dept renamed to Department of English)
+- Moved:     1 Account  (School of Business moved to North Campus)
+- Unchanged: 19 Accounts (reused, no write)
+- Extra in org (left untouched): 1  (Legacy Extension Center)
+- Business Profiles created: 2 (for the new Departments)
+```

package/skills/education-cloud-multi-campus-configure/examples/sample_hierarchy_input.csv

@@ -0,0 +1,29 @@
+Name,LevelType,Level,ParentName
+Pacifica State University System,System,1,
+Pacifica State University System - Northern Region,Region,2,Pacifica State University System
+Pacifica State University System - Southern Region,Region,2,Pacifica State University System
+Redwood Campus,Campus,3,Pacifica State University System - Northern Region
+Bayview Campus,Campus,3,Pacifica State University System - Northern Region
+Harbor Campus,Campus,3,Pacifica State University System - Southern Region
+College of Engineering,College,4,Redwood Campus
+College of Arts & Sciences,College,4,Redwood Campus
+College of Business,College,4,Bayview Campus
+College of Health Sciences,College,4,Harbor Campus
+Department of Computer Science,Department,5,College of Engineering
+Department of Mechanical Engineering,Department,5,College of Engineering
+Department of Biology,Department,5,College of Arts & Sciences
+Department of English,Department,5,College of Arts & Sciences
+Department of Finance,Department,5,College of Business
+Department of Marketing,Department,5,College of Business
+Department of Nursing,Department,5,College of Health Sciences
+Department of Public Health,Department,5,College of Health Sciences
+BS in Computer Science,Program,6,Department of Computer Science
+MS in Artificial Intelligence,Program,6,Department of Computer Science
+BS in Mechanical Engineering,Program,6,Department of Mechanical Engineering
+BS in Biology,Program,6,Department of Biology
+BA in English Literature,Program,6,Department of English
+BS in Finance,Program,6,Department of Finance
+MBA in Finance,Program,6,Department of Finance
+BS in Marketing,Program,6,Department of Marketing
+BS in Nursing,Program,6,Department of Nursing
+MS in Public Health,Program,6,Department of Public Health

package/skills/education-cloud-multi-campus-configure/examples/sample_hierarchy_input_edgecases.csv

@@ -0,0 +1,16 @@
+Name,LevelType,Level,ParentName
+Pacifica State University System,System,1,
+Pacifica State University System - Northern Region,Region,2,Pacifica State University System
+Pacifica State University System - Southern Region,Region,2,Pacifica State University System
+Redwood Campus,Campus,3,Pacifica State University System - Northern Region
+Bayview Campus,Campus,3,Pacifica State University System - Northern Region
+Harbor Campus,Campus,3,Pacifica State University System - Southern Region
+School of Arts & Sciences,College,4,Redwood Campus
+School of Arts & Sciences,College,4,Bayview Campus
+College of Engineering,College,4,Redwood Campus
+College of Nursing,College,4,Harbor Campus
+Department of Biology,Department,5,School of Arts & Sciences
+CS Dept,Department,5,College of Engineering
+Department of Orphaned Studies,Department,5,College of Nonexistent
+BS in Biology,Program,6,Department of Biology
+BS in Computer Science,Program,6,CS Dept

package/skills/education-cloud-multi-campus-configure/references/account_recordtype_prerequisite.md

@@ -0,0 +1,44 @@
+# Missing Account RecordType — Prerequisite Handling (Step 3.5)
+
+This skill can be run standalone, without any prior org-setup skill having run first. A common gap on a
+fresh org: `Account/describe` returns only the `Master` RecordType — no institutional/business
+RecordType exists yet to select in Step 3.5. Treat this as a missing prerequisite to resolve, not a
+dead end.
+
+## Procedure
+
+1. **Tell the user** the org has no non-Master Account RecordType, and this skill needs one to
+   distinguish institution Accounts (System/Campus/College/Department) from other Account records.
+2. **Ask for a Label** if the user hasn't already stated one (e.g. "Institution", "Educational
+   Institution", "Business Account") — offer "Institution" as the default suggestion. Derive the
+   `DeveloperName` from the label (strip spaces/special chars, e.g. `Institution`).
+3. **Confirm before creating** — same create/update/delete confirmation convention as every other
+   write in this skill: "Create Account RecordType '[Label]' (API name `Account.[DeveloperName]`)?
+   (Yes/No)". If "No": stop the workflow — the hierarchy cannot be created without a RecordType.
+4. **Create via Tooling API** (write-enabled `dispatch`, not `dispatch_readonly`):
+   ```json
+   {
+     "url": "/services/data/v68.0/tooling/sobjects/RecordType",
+     "method": "POST",
+     "body": {
+       "FullName": "Account.[DeveloperName]",
+       "Metadata": {
+         "label": "[Label]",
+         "active": true,
+         "description": "Institutional hierarchy Account (System/Campus/College/Department)"
+       }
+     }
+   }
+   ```
+5. **Cold-verify** — re-run the Step 3.5 describe call. Confirm the new entry appears in
+   `recordTypeInfos`.
+   - **If `available: true` for the running user** — capture `recordTypeId`, proceed with Step 3.5's
+     normal selection logic.
+   - **If `available: false`** — RecordType creation does not automatically grant profile/permission-set
+     visibility (there is no supported API for Record Type Visibility assignment). Tell the user to
+     assign it manually: Setup → Profiles (or Permission Sets) → Record Type Visibilities → assign the
+     new RecordType to their own profile/permission set → Save. Wait for their confirmation, then
+     repeat the describe call to cold-verify `available: true` before proceeding.
+6. **If Tooling API creation fails** (e.g. no Tooling API access): fall back to manual creation —
+   instruct the user via Setup → Object Manager → Account → Record Types → New, then repeat the
+   describe call to cold-verify.

package/skills/education-cloud-multi-campus-configure/references/delta_computation.md

@@ -0,0 +1,33 @@
+# Delta Computation Reference — Update Mode (Step 5)
+
+Full matching and cycle-rejection algorithm for reconciling the desired hierarchy against the org's current one.
+
+## Traverse the current tree from the root
+
+Starting at the supplied System Account Id, read children level-by-level via the SObject child-relationship resource:
+
+- `GET /services/data/v68.0/sobjects/Account/[Account Id]/ChildAccounts` via `dispatch_readonly` (see `references/mcp-invocation.md`)
+- This returns the direct child Accounts (`body.records[]`, each with `Id`, `Name`, `ParentId`). Recurse into each child's Id to build the full `existingTree`.
+- If `ChildAccounts` is unavailable in the org, fall back to a SOQL `/query` with the query text passed as `queryParams.q` (never appended inline to the URL as `?q=` — that has 404'd on some orgs). If both fail, ask the user to paste the current structure (Name + Account Id per node) instead.
+
+## Match desired vs. current
+
+By Name within the same sibling group (names are unique per sibling group — see Rules). For each desired node, walking from the root down:
+
+- **Match found** (same Name under the matched parent) → reuse its Account Id; recurse into its children. No write.
+- **No match** (desired node absent under that parent) → mark **CREATE**; every desired descendant beneath it is also CREATE (parent Id resolves once the parent is created).
+
+## Extra nodes
+
+Present in the org but absent from the desired structure → mark **EXTRA**. Do NOT delete. List them for the user in the preview.
+
+## Explicit renames / moves
+
+Only when the user asks for them by name — a bare desired tree cannot distinguish a rename from a delete-plus-add:
+
+- **Rename**: resolve the target node's Account Id from `existingTree` by its current name/path → mark **RENAME** (new Name).
+- **Move**: resolve both the node's Id and the new parent's Id → mark **MOVE** (new ParentId). Reject a move that would place a node under its own descendant (cycle) — stop with an error before writing.
+
+## Result
+
+A delta list of CREATE / RENAME / MOVE actions plus an EXTRA report. If the delta is empty and no renames/moves were requested, tell the user the org already matches the desired structure and skip to Step 9 (verify).

package/skills/education-cloud-multi-campus-configure/references/error_handling.md

@@ -0,0 +1,198 @@
+# Error Handling — API and Data Issues
+
+Recovery strategies for common errors during hierarchy creation.
+
+## API Rate Limit Errors
+
+**Error**: `API rate limit exceeded` or HTTP 429
+
+**When it occurs**: During bulk BusinessProfile creation (Step 8) or when creating/patching many Accounts in rapid succession (Step 7)
+
+**Resolution**:
+
+1. **Track what succeeded**: Parse API response to identify which records were created successfully
+2. **Retry failed records only**: Wait 2 seconds, then retry only the records that failed
+3. **Exponential backoff**: If retry fails, wait 4 seconds, then 8 seconds (max 3 retries)
+4. **Report status**: Print which records succeeded vs. failed after each attempt
+
+**Example**:
+```text
+⚠️ API rate limit hit during BusinessProfile creation
+
+Status: 21 of 23 BusinessProfiles created
+Failed: 2 department-level profiles
+  - Nursing Department (under School of Health Sciences, Main Campus)
+  - Allied Health Department (under School of Health Sciences, Main Campus)
+
+Retrying in 2 seconds...
+```text
+
+After retry:
+```text
+Retry successful — all 23 BusinessProfiles created
+```text
+
+**Implementation**: Retry with exponential backoff (sleep 2s, 4s, 8s between attempts). For each retry:
+- `mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/BusinessProfile", "method": "POST", "body": {"AccountId": "[Account ID]"}})`
+
+---
+
+## Duplicate Record Errors
+
+**Error**: `DUPLICATE_VALUE: duplicate value found`
+
+**When it occurs**: Creating Account with name that already exists at the same hierarchy level
+
+**Resolution**:
+
+1. **Check if existing record is part of this hierarchy**: Look it up in `existingTree` (loaded in Step 5 via the `ChildAccounts` GET, or a SOQL `/query` — both are routable) — match on name under the intended parent.
+2. **If yes (reused / leftover from previous run)**: Reuse the existing Account ID instead of creating new — this is the normal update-mode path
+3. **If no (different hierarchy)**: Append disambiguating suffix to name (e.g., campus name in parentheses)
+
+**Example**:
+```text
+⚠️ Account "School of Arts & Sciences" already exists
+
+Found existing record under: North Campus
+Creating under: Main Campus
+
+Resolution: Renaming to "School of Arts & Sciences (Main Campus)"
+```text
+
+---
+
+## Parent Record Not Found
+
+**Error**: `INVALID_FIELD: ParentId — invalid cross-reference key`
+
+**When it occurs**: Attempting to create child record before parent exists
+
+**Root cause**: Workflow steps executed out of order, or API creation for parent failed silently
+
+**Resolution**:
+
+1. **Verify parent was created**: Check that the parent Account ID exists in `accountMap` (created this run) or in `existingTree` (reused in update mode)
+2. **If missing**: Re-run creation for that parent level, then retry child creation
+3. **If parent ID present but reference fails**: Query Salesforce to confirm parent record exists: `mcp__headless-360__dispatch_readonly({"url": "/services/data/v68.0/sobjects/Account/$PARENT_ID", "method": "GET"})`
+
+**Prevention**: Follow workflow step order strictly — create parents before children.
+
+---
+
+## BusinessProfile Field Not Found
+
+**Error**: `INVALID_FIELD: No such column 'AccountId' on sobject of type BusinessProfile`
+
+**When it occurs**: User's org does not have Education Cloud provisioned, or BusinessProfile object not available
+
+**Resolution**:
+
+1. **Stop workflow**: Cannot proceed without Education Cloud
+2. **Report to user**:
+   ```text
+   ⚠️ BusinessProfile creation failed — Education Cloud may not be provisioned
+
+   Error: AccountId field not found on BusinessProfile object
+
+   This usually means:
+   • Education Cloud managed package not installed
+   • User lacks Education Cloud license
+   • Org does not have Education Cloud feature enabled
+
+   Check prerequisites: IndustriesEducation.userHasEducationCloudAccess
+
+   Would you like to proceed with Account creation only (no BusinessProfiles)?
+   ```
+
+3. **Fallback**: Offer to create Account hierarchy without BusinessProfiles
+
+---
+
+## Missing Fields in API Response
+
+**Error**: sObject API POST returns success but does not include `id` field in response
+
+**When it occurs**: Rare API issue or malformed response
+
+**Resolution**:
+
+1. **Prefer capturing `body.id` from the create response** — it is present on normal `201` responses. A SOQL `/query` lookup by Name under the intended parent also works as a fallback if the create response was lost.
+2. **If `body.id` truly missing on a `201`**: do NOT blindly re-POST (risks a duplicate Account). Report to user with the node Name + intended parent Id and ask how to proceed (re-create vs. locate manually in the org).
+3. **Log issue**: Print warning that the API response was incomplete, including the node Name and parent Id.
+
+---
+
+## Timeout Errors
+
+**Error**: `ERROR: Request timeout` or `ETIMEDOUT`
+
+**When it occurs**: Creating many records in quick succession, or org has slow custom triggers
+
+**Resolution**:
+
+1. **Batch size**: Create records in smaller batches (max 10 per batch) with 1-second pause between batches
+2. **Retry failed records**: Use same retry logic as rate limit errors (exponential backoff)
+3. **Identify slow triggers**: If timeout persists, check if Account or BusinessProfile has custom Apex triggers — these can slow creation
+
+**Batching**: Split into batches of max 10 records, 1-second pause between batches. For each record in a batch:
+- `mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/Account", "method": "POST", "body": {"Name": "[Node name]", "RecordTypeId": "[recordTypeId resolved in Step 3.5]", "ParentId": "[Parent node's Account ID]"}})`
+  (Use `RecordTypeId` with the runtime-resolved value — never a hardcoded Id. Omit `ParentId` for the System node.)
+
+---
+
+## Incomplete Parsing (Zero Records at Level)
+
+**Issue**: Parser extracts zero colleges or zero departments for a campus
+
+**When it occurs**: PDF/HTML parsing misses section, or input format is non-standard
+
+**Resolution**:
+
+1. **Confirm with user before creating**: Show parsed structure and ask if zero records at that level is correct
+2. **Offer to continue anyway**: User may add colleges/departments manually later
+3. **Suggest simplified input**: If parsing quality is poor, ask user to provide plain text description instead
+
+**Example confirmation**:
+```text
+I extracted this structure:
+
+System: Riverside Community College System
+├─ Campus: Main Campus
+│  └─ (No colleges found)
+└─ Campus: North Campus
+   ├─ College: Technical Education
+   └─ College: School of Arts & Sciences
+
+Main Campus has no colleges — is this correct, or should I look for college info elsewhere?
+
+[1] Correct — proceed
+[2] Missing data — I'll provide college list
+```text
+
+---
+
+## General Error Handling Pattern
+
+For any unexpected API error:
+
+1. **Capture full error message**: Log complete error text from API response
+2. **Identify which record failed**: Include record Name and hierarchy level in error report
+3. **Report status to user**: Show what succeeded so far vs. what failed
+4. **Offer retry or manual fix**: Ask user if they want to retry, skip failed record, or provide corrected info
+5. **Do not fail silently**: Every error must be reported to user with context
+
+**Example error report**:
+```text
+⚠️ Error creating Department Account
+
+Record: Computer Science Department
+Parent: Technical Education (College)
+Error: FIELD_CUSTOM_VALIDATION_EXCEPTION: Name must be unique within College
+
+Status: 11 of 12 Department Accounts created successfully
+
+Resolution options:
+[1] Rename to "Computer Science Department (Tech Ed)" and retry
+[2] Skip this department
+[3] I'll provide a different name
+```text

package/skills/education-cloud-multi-campus-configure/references/foundation_prerequisites.md

@@ -0,0 +1,54 @@
+# Step 0 — Foundation Prerequisites
+
+This skill can run standalone, without any other Education Cloud setup skill running first. Verify
+these before Step 1 — they are shared across the EDU skill family (also required by
+`education-cloud-domain-configure`, `education-cloud-academic-calendar-generate`,
+`education-cloud-course-catalog-migrate`). A gap here is a missing prerequisite to resolve, not a
+dead end — self-heal what's API-writable, ask/confirm before any write, otherwise instruct manual
+Setup and wait for confirmation.
+
+## Checks (in order — each can stop the workflow if unresolved)
+
+1. **Org edition** — `GET /services/data/v68.0/query`, `queryParams: {"q": "SELECT OrganizationType FROM Organization"}`
+   (singleton, no Id). Must be Enterprise, Performance, Unlimited, or Developer Edition. Cannot be
+   fixed via API or Setup — if wrong edition, tell the user Education Cloud requires Enterprise+ and
+   stop.
+
+2. **Lightning Experience enabled** — no supported read API; if BusinessProfile/Account describe
+   calls below succeed the org is on Lightning (Classic-only orgs can't run this skill). If any call
+   in this section fails with an org-mode-related error, instruct: Setup → User Interface → Enable
+   Lightning Experience. Wait for confirmation, retry.
+
+3. **Education Cloud license provisioned** — permission set names for this vary by org/release
+   (confirmed live: one org shipped `EducationCloudAccess`, `AgentforceForEducationCloudAccess`, and
+   `EinsteinForEducationCloudAccess` — never `EducationCloudUser`). Do not match on a single exact
+   name. `GET /services/data/v68.0/query`, `queryParams: {"q": "SELECT Id, Name FROM PermissionSet
+   WHERE Name LIKE '%EducationCloud%'"}`. Rows found → provisioned, proceed. Zero rows → cross-check
+   before concluding anything: `GET /services/data/v68.0/sobjects/BusinessProfile/describe` — if it
+   404s or returns `createable:false`, license is genuinely not provisioned; tell the user and stop
+   (cannot be fixed via API, they need to provision the license). If it 200s with `createable:true`
+   despite the zero-row permission-set query, treat the license as provisioned and note the mismatch
+   rather than trusting the permission-set name search alone.
+
+4. **Running user has Education Cloud access** — `GET /services/data/v68.0/query`,
+   `queryParams: {"q": "SELECT Id, PermissionSet.Name FROM PermissionSetAssignment WHERE
+   AssigneeId='<running user Id>' AND PermissionSet.Name LIKE '%EducationCloud%'"}` (resolve the
+   running user's Id first — ask for their username if unknown). No rows → no API route to
+   self-assign. Instruct: Setup → Permission Sets → find the org's actual Education Cloud permission
+   set (from Check 3's query results) → Manage Assignments → add the running user. Wait for
+   confirmation, then re-run this check before proceeding.
+
+5. **Education Cloud Foundation enabled** — `GET /headless/invoke/platform/education-cloud-settings`
+   via `dispatch_readonly`, inspect `educationCloudEnabled`.
+   - `true` → proceed to Step 1.
+   - `false` → ⚠️ **IRREVERSIBLE — one-way by design.** Warn the user explicitly; do NOT promise a
+     revert. Ask for confirmation: "Education Cloud Foundation isn't enabled on this org. Enable it
+     now? This cannot be turned off afterward." On "No": stop — the hierarchy cannot be created
+     without it. On "Yes": `PATCH /headless/invoke/platform/education-cloud-settings/enable-education-cloud`
+     (empty body, write-enabled `dispatch`). Cold-verify by repeating the GET — confirm
+     `educationCloudEnabled: true` on a fresh read.
+   - **If the invoke endpoint errors, or cold-verify still shows `false`**: fall back to manual UI —
+     Setup → Quick Find → "Set Up Education Cloud" → Select Set Up Education Cloud → Toggle "Enable
+     Education Cloud" → Save. Wait for user confirmation, then cold-verify again before proceeding.
+
+Do not proceed to Step 1 until all five checks pass.

package/skills/education-cloud-multi-campus-configure/references/gotchas.md

@@ -0,0 +1,16 @@
+# Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Rename vs. delete-plus-add is indistinguishable from a bare desired tree | Only treat a change as RENAME/MOVE when the user names it explicitly; otherwise an absent node is CREATE and an extra node is EXTRA (report, don't delete) |
+| Update run recreates everything (duplicates) | Ensure Step 4 detected update mode and Step 5 loaded `existingTree`; a missing root Id defaults to new setup — confirm mode with the user |
+| `ChildAccounts` relationship returns partial/paged results | Follow `nextRecordsUrl`/paging if present; if the relationship is unavailable, fall back to a SOQL `/query` with `WHERE ParentId = ...` (confirmed routable), or ask the user to paste current node Ids |
+| API rate limit during Business Profile creation | Retry failed records after 2-second delay; print which records succeeded vs. failed |
+| Ambiguous college-to-campus mapping in parsed text | Ask user: "Which campus does [College name] belong to?" before creating College Account |
+| Duplicate names across campuses (e.g., "School of Arts & Sciences" on multiple campuses) | Append campus name to college name: "School of Arts & Sciences (Main Campus)" |
+| PDF parsing extracts noise (headers, footers, page numbers) | Filter lines matching common noise patterns before parsing hierarchy; see `references/hierarchy_parsing_rules.md` |
+| User uploads flattened list without parent relationships stated | Ask user to clarify structure: "I see these names — please describe which items are campuses, colleges, and departments" |
+| BusinessProfile creation fails with "AccountId field not found" | User's org may not have Education Cloud provisioned; check access prerequisites returned error |
+| User expects a stored materialized-path field to read back | There is none — build the path on demand by GET-ing the Account and walking its ParentId chain to the System root, joining Names with ` / ` |
+| Requested URL is blocked/unreachable during Step 1 | Do not silently substitute another source (e.g. a research agent pulling from Wikipedia) — stop and ask the user for a PDF, CSV, or pasted text from the institution's own site |
+| User wants `InstitutionType` set on a Business Profile for a non-K-12/higher-ed institution (vocational, allied health, satellite/extension) | `InstitutionType` is a managed, restricted picklist (typically `Public`/`Private`/`Charter` only) — cannot be extended; tell the user upfront and offer `Description` as the only workaround field |

package/skills/education-cloud-multi-campus-configure/references/hierarchy_parsing_rules.md

@@ -0,0 +1,133 @@
+# Hierarchy Parsing Rules
+
+Decision logic for resolving ambiguous institutional structures during parsing.
+
+**Key principle**: Support any number of hierarchy levels (2+). Do not assume fixed level names or depth. Infer structure from source content (nesting, indentation, headings, list structure).
+
+## Parsing PDF Documents
+
+### Noise Filtering
+
+Before parsing hierarchy content, drop lines matching common noise patterns (case-insensitive):
+
+Common noise indicators:
+- Page numbers: `Page 1`, `1`, `- 2 -`
+- Copyright symbols: `© 2025`, `® Company Name`
+- URLs and email addresses
+- Single-word lines at top/bottom of pages (likely headers/footers)
+
+### Hierarchy Level Detection
+
+**Approach**: Use indentation, list nesting, and keyword patterns to infer levels. Do not map to fixed level names (Campus/College/Department) — use whatever names appear in source.
+
+| Pattern | Likely Level Type | Example |
+|---------|------------------|---------|
+| Contains "System", "District", all caps, or ends in "System" | Top level (System) | `RIVERSIDE COMMUNITY COLLEGE SYSTEM`, `State University System` |
+| Contains "Campus", "Location", "Site", geographic qualifier | Geographic level | `Main Campus`, `North Location`, `Downtown Campus`, `Regional Center` |
+| Contains "School of", "College of", "Faculty of" | Academic division | `School of Arts & Sciences`, `College of Engineering`, `Faculty of Medicine` |
+| Contains "Department", "Dept", "Division", "Program" | Sub-division | `Computer Science Department`, `Accounting Dept`, `Marketing Division` |
+| Contains "Unit", "Team", "Section", "Lab" | Lowest level | `Research Unit`, `Clinical Lab`, `Admissions Team` |
+
+**If source has >4 levels**: Parse all levels. Store each node's level name exactly as it appears (e.g., "Region", "District", "Branch", "Unit").
+
+### Ambiguous Cases
+
+**Problem**: Child node appears without explicit parent.
+
+**Example input**:
+```text
+Main Campus
+North Campus
+School of Business
+School of Arts & Sciences
+```text
+
+**Resolution**:
+1. If children appear immediately after a parent name without intervening parents → assign to that parent
+2. If children appear in a separate section → ask user: "I found these nodes: [list]. Which parent does each belong to?"
+
+**Problem**: Duplicate names across branches (e.g., "School of Arts & Sciences" under multiple parents).
+
+**Example**:
+```text
+Main Campus
+  - School of Arts & Sciences
+North Campus
+  - School of Arts & Sciences
+```text
+
+**Resolution**:
+Append parent name in parentheses:
+- `School of Arts & Sciences (Main Campus)`
+- `School of Arts & Sciences (North Campus)`
+
+## Parsing Website HTML
+
+### Content Extraction Priority
+
+1. **Navigation menus**: Look for `<nav>` elements with class names like `campus-nav`, `org-structure`, `hierarchy`
+2. **Unordered lists**: Parse `<ul>` with nested `<li>` elements as hierarchy levels — each nesting level = one hierarchy level
+3. **Headings**: Use heading levels to infer hierarchy depth: `<h1>` → Level 0, `<h2>` → Level 1, `<h3>` → Level 2, etc.
+4. **Breadcrumbs**: Extract hierarchy from breadcrumb navigation (`<nav aria-label="breadcrumb">`)
+
+**Do not assume fixed mapping** (h2=Campus, h3=College). Just track relative depth: h1 is top, h2 is one level down, etc. Fetch the page, then read off the heading tags (`<h2>`, `<h3>`, `<h4>`, …) at each nesting depth. If HTML structure is non-standard, fall back to asking user for clarification.
+
+## Parsing Plain Text Description
+
+### Expected Format
+
+Users may describe hierarchy in natural language:
+
+> "We have Riverside Community College System with three campuses: Main Campus, North Campus, and South Campus. Main Campus has School of Business and School of Health Sciences. North Campus has Technical Education. Each school has departments."
+
+### Extraction Strategy
+
+1. **System**: First sentence often contains system name (top level)
+2. **Level 1**: Look for keywords indicating first subdivision (campuses, regions, locations, branches)
+3. **Level 2**: Look for "has", "includes", "contains" followed by organizational unit names (schools, colleges, divisions)
+4. **Level 3+**: Look for nested indicators ("each X has Y", "programs:", "departments:"), or recursive "contains"/"includes" patterns
+
+**Parse based on nesting depth, not fixed level names.** If text says "Region → District → Campus → College → Department", parse all 6 levels (including System).
+
+### Validation Questions
+
+Ask user to confirm when:
+- Zero children found for a parent node
+- Ambiguous parent-child relationship (e.g., "Computer Science" — is it at level 2 or level 3?)
+- Unusual depth (1 level only, or >6 levels)
+
+**Validation prompt template**:
+```text
+I extracted this structure:
+
+System: [Name]
+├─ Level 1: [Name]
+│  └─ (No children found)
+└─ Level 1: [Name]
+
+Is this correct, or should I look for child nodes elsewhere?
+```text
+
+## Edge Cases
+
+| Scenario | How to Handle |
+|----------|---------------|
+| Only 1 level below System (flat structure) | Ask user: "I found a flat structure — should I create this as-is, or do you have additional sub-levels?" |
+| Multiple system-level entities | Clarify: "I found multiple top-level names — which one is the System?" |
+| Children listed without parent | Ask: "Which parent do these nodes belong to: [list]" |
+| Abbreviations in source (e.g., "CS Dept") | Expand to full name: "Computer Science Department" (ask user if unclear) |
+| >6 hierarchy levels | Confirm: "I found [N] levels — is this correct, or should some levels be combined?" |
+
+## Confidence Scoring
+
+Before confirming structure with user, assess parsing confidence:
+
+| Confidence | Criteria | Action |
+|-----------|----------|--------|
+| High | 2+ levels present, clear parent-child relationships, no duplicates | Proceed to confirmation |
+| Medium | Ambiguity (duplicate names resolved, or single missing level) | Show structure and ask for confirmation |
+| Low | Missing levels, unclear parent relationships, or extensive noise | Ask user for clarification before showing structure |
+
+High/Medium confidence: show parsed structure and ask "Should I proceed?"
+
+Low confidence: show what was extracted and ask "I had trouble parsing — can you clarify the structure?"

package/skills/education-cloud-multi-campus-configure/references/mcp-invocation.md

@@ -0,0 +1,75 @@
+# MCP Invocation Reference — Multi-Campus Hierarchy
+
+`headless-360` is the default transport (see Mechanism in `SKILL.md` for the health-probe and fallback
+sequence). When it's healthy, every operation below dispatches through it via four meta-tools:
+
+- `mcp__headless-360__discover(query)` — semantic search over the indexed operation catalog
+- `mcp__headless-360__describe(id)` — pull the schema and canonical route for one operation
+- `mcp__headless-360__dispatch_readonly({url, method, queryParams?, body?})` — GET / read-only HTTP
+- `mcp__headless-360__dispatch({url, method, body?, queryParams?})` — POST / PATCH / DELETE HTTP
+
+**Dispatch takes raw HTTP**, not `{operation_id, arguments}`. Give it the full `url`
+(`/services/data/v68.0/...`), `method`, optional `body`, and optional `queryParams` (camelCase — the
+tool rejects `query_params`, and a SOQL string must go in `queryParams.q`, never appended inline to
+the URL as `?q=`). The server signs the request with the JWT bound to the current MCP session and
+forwards it to the org — the skill never handles a credential, org id, or alias.
+
+**A `discover` miss does NOT mean the route is absent.** The standard `/sobjects/...` and `/query`
+REST routes this skill uses are not always ranked first (or indexed) in the discovery corpus —
+`describe` on the canonical operation still returns the schema, and `dispatch*` on the exact path
+still works. Only if the GET/POST/PATCH/DELETE itself returns 404 should you treat the route as
+unavailable on this org.
+
+## Response envelope
+
+`dispatch*` returns the REST response singly wrapped:
+
+```json
+{ "status_code": 200, "body": { "totalSize": 1, "records": [ { "Id": "001..." } ] } }
+```
+
+Read the relevant field from `body`. Status codes: `200` read success; `201` record created; `400`
+bad body or a business-rule rejection — read `body[0].errorCode`; `403` access/feature gap; `404` the
+endpoint/impl is not present on this org.
+
+## Calls used by this skill
+
+**Step 3.5 — resolve Account RecordType**
+```text
+mcp__headless-360__dispatch_readonly({"url": "/services/data/v68.0/sobjects/Account/describe", "method": "GET"})
+```
+
+**Step 5 — load current hierarchy**
+```text
+mcp__headless-360__dispatch_readonly({"url": "/services/data/v68.0/sobjects/Account/[Account Id]/ChildAccounts", "method": "GET"})
+```
+Fallback if `ChildAccounts` is unavailable:
+```text
+mcp__headless-360__dispatch_readonly({
+  "url": "/services/data/v68.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id, Name, ParentId FROM Account WHERE ParentId = '[Account Id]'" }
+})
+```
+
+**Step 7 — create / rename / move / delete Account**
+```text
+mcp__headless-360__dispatch({
+  "url": "/services/data/v68.0/sobjects/Account",
+  "method": "POST",
+  "body": { "Name": "[Node name]", "RecordTypeId": "[recordTypeId]", "ParentId": "[Parent Account Id]" }
+})
+mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/Account/[Account Id]", "method": "PATCH", "body": {"Name": "[new name]"}})
+mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/Account/[Account Id]", "method": "PATCH", "body": {"ParentId": "[new parent Account Id]"}})
+mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/Account/[Account Id]", "method": "DELETE"})
+```
+
+**Step 8 — create BusinessProfile**
+```text
+mcp__headless-360__dispatch({"url": "/services/data/v68.0/sobjects/BusinessProfile", "method": "POST", "body": {"AccountId": "[Account ID]"}})
+```
+
+**Step 9 — cold verification**
+```text
+mcp__headless-360__dispatch_readonly({"url": "/services/data/v68.0/sobjects/Account/[Account Id]", "method": "GET"})
+```