@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/platform-lightning-type-widget-coordinate/references/lightning-type-discovery.md

@@ -0,0 +1,124 @@
+# Lightning Type Discovery Procedure
+
+Use this procedure in Phase 2 of the orchestrator workflow. The goal is to resolve the user's named Lightning Type into an on-disk `schema.json`, verify it is **Apex-backed** (the only kind this orchestrator handles), and capture a SHA-256 fingerprint plus the Apex class FQN for the Phase 5 P0 gate and the Phase 4 widget-skill handoff.
+
+> **Applies to the `existing-lightning-type-with-widget` path only.** Skipped on the `new-lightning-type-with-widget` path (the user is creating a new Lightning Type — there is nothing to discover). Do not run this procedure when Phase 1 picks `new-lightning-type-with-widget`.
+
+---
+
+The sequence is **find → verify → ensure-class**: locate the Lightning Type (local project first, then org), verify it is Apex-backed, then ensure its backing Apex class is in the local project (retrieving it from the org if needed). The downstream widget skill and the Phase 5 `field-trace` gate both read the `.cls` to enumerate `@AuraEnabled` fields — a Lightning Type without its class in the local project is unrenderable.
+
+---
+
+## Step 1 — Search the local project files
+
+Look for any of:
+
+- `force-app/**/lightningTypes/<TypeName>/schema.json`
+- `<pkgDir>/lightningTypes/<TypeName>/schema.json` where `<pkgDir>` = `<packageDirectories[].path>/main/default` (per `platform-widget-generate/references/widget-bundle-layout.md`).
+
+Match `<TypeName>` case-insensitively for the search but preserve the directory's actual case for outputs.
+
+**Outcomes:**
+
+- **Exactly one match.** Continue to Step 3 (verify Apex-backed) before capturing path + SHA-256.
+- **Multiple matches** (case-insensitive name collision, multiple package directories, etc.). List candidates with their full paths to the user. Ask: *"Multiple Lightning Types match `<TypeName>`. Which one should the widget ground on?"* Wait for the user's pick, then continue to Step 3.
+- **No match — do not skip.** Continue to Step 2 (org retrieve).
+
+---
+
+## Step 2 — Retrieve from the org
+
+If the Lightning Type is not in the local project, run:
+
+```bash
+sf project retrieve start --metadata LightningTypeBundle:<TypeName>
+```
+
+The retrieve writes the Lightning Type bundle into the project under the configured package directory.
+
+**Outcomes:**
+
+- **Retrieve succeeds with one Lightning Type.** Continue to Step 3 (verify Apex-backed) before capturing path + SHA-256 + Apex class FQN.
+- **Retrieve succeeds with multiple Lightning Types** (wildcard match; `LightningType:*<partial>*`). List them. Ask the user to pick. Re-retrieve with the exact name if needed, then continue to Step 3.
+- **Retrieve reports "no metadata found".** The Lightning Type does not exist in the org. Continue to Step 5.
+- **Retrieve fails with an error** (auth expired, org unreachable, permission denied, etc.). Surface the CLI error verbatim. Ask the user to fix and re-run.
+
+---
+
+## Step 3 — Verify the Lightning Type is Apex-backed
+
+Read the located `schema.json`. Inspect the root `lightning:type` value.
+
+| Root `lightning:type` value | Decision |
+|---|---|
+| Starts with `@apexClassType/` (for example `@apexClassType/c__AccountBriefing`) | **Apex-backed.** Continue. Capture the FQN — everything after `@apexClassType/`. The FQN points at the **outer Apex class**, whose `@AuraEnabled` fields define the payload shape. The `$<InnerClass>` suffix is not used at the Lightning Type root; inner classes live as `List<Inner>` fields on the outer class. |
+| `lightning__objectType` (with primitive `properties`) | **Object/JSON-based.** Out of scope for this orchestrator. Tell the user: *"`<TypeName>` is an object/JSON-based Lightning Type. This orchestrator only handles Apex-backed Lightning Types. Use `platform-custom-lightning-type-generate` and `platform-widget-generate` separately for this case."* Stop. |
+| Anything else | Surface the unrecognized value to the user and stop. Do not guess. |
+
+When Apex-backed, capture path + SHA-256 + Apex class FQN, then continue to Step 4 (do not stop here — the class must be verified in the local project first).
+
+---
+
+## Step 4 — Ensure the backing Apex class is in the local project
+
+**Both entry paths converge here** — a Lightning Type located in the local project (Step 1) and one retrieved from the org (Step 2) both reach this step. Locating the Lightning Type does NOT guarantee its backing class is local: `sf project retrieve --metadata LightningTypeBundle:<TypeName>` pulls only the bundle, not the referenced Apex class, and a hand-authored or partially-synced local bundle can reference a class that was never committed.
+
+Parse `<ClassName>` from the Apex class FQN captured in Step 3 (`@apexClassType/<namespace>__<ClassName>` → `<ClassName>`; strip any `$<Inner>` suffix — retrieve the outer class). Check whether `<pkgDir>/classes/<ClassName>.cls` exists in the local project.
+
+**Outcomes (covering all four LT × class scenarios):**
+
+| Lightning Type source | `.cls` in local project? | Action |
+|---|---|---|
+| local project (Step 1) | yes | Nothing to do — continue. |
+| local project (Step 1) | no | Retrieve the class (below). |
+| org-retrieve (Step 2) | yes | Nothing to do — continue. |
+| org-retrieve (Step 2) | no | Retrieve the class (below). |
+
+When the class is absent, retrieve it by name:
+
+```bash
+sf project retrieve start --metadata ApexClass:<ClassName>
+```
+
+`ApexClass` is the metadata type; `<ClassName>` is the bare class name — no namespace prefix, no `.cls` extension. For multiple classes, comma-separate: `--metadata ApexClass:OrderSummary --metadata ApexClass:OrderLine`.
+
+**Retrieve outcomes:**
+
+- **Succeeds.** The `.cls` now lands under `<pkgDir>/classes/`. Continue.
+- **Reports "no metadata found".** The backing class exists neither in the local project nor in the org — the Lightning Type is **unrenderable** (its payload shape is undefined). Surface this to the user verbatim and STOP. Do not hand the widget skill a Lightning Type whose `@AuraEnabled` fields cannot be enumerated.
+- **Fails with an error** (auth expired, org unreachable, permission denied). Surface the CLI error verbatim. Ask the user to fix and re-run.
+
+Done — path + SHA-256 + Apex class FQN captured, and the `.cls` confirmed in the local project.
+
+---
+
+## Step 5 — Lightning Type does not exist anywhere
+
+Tell the user the Lightning Type is not in the local project and not in the org. Offer to **switch to the `new-lightning-type-with-widget` path** — generate a new Apex-backed Lightning Type (with its Apex class, auto-engaged) before authoring the widget.
+
+Wait for the user's confirmation. Do not silently pick. If the user does not want a Lightning Type at all, route them to `platform-widget-generate` directly — that case is outside this orchestrator's scope.
+
+---
+
+## Staleness rule
+
+Do **not** maintain a cross-session cache. Each invocation of this orchestrator re-reads the local project and re-retrieves from the org as needed. Any single retrieve result is treated as authoritative for the lifetime of that orchestrator run.
+
+---
+
+## Output of Phase 2
+
+```text
+lightningTypeSchema = {
+  name: "<TypeName>",
+  path: "<pkgDir>/lightningTypes/<TypeName>/schema.json",
+  sha256: "<hex>",
+  source: "fs" | "org-retrieve",
+  apexClassFqn: "<namespace>__<ClassName>",   # outer class only — no $<Inner> form
+  apexClassPath: "<pkgDir>/classes/<ClassName>.cls",   # guaranteed in the local project by Step 4
+  apexClassSource: "fs" | "org-retrieve",
+}
+```
+
+Phase 2 always ends with a non-null `lightningTypeSchema` on the `existing-lightning-type-with-widget` path, **and with the backing `.cls` confirmed in the local project** (per Step 4). If discovery fails and the user does not switch to `new-lightning-type-with-widget`, or if the backing Apex class exists nowhere, the orchestrator stops.

package/skills/platform-lightning-type-widget-coordinate/references/validation-gates.md

@@ -0,0 +1,130 @@
+# Validation Gates
+
+The orchestrator runs only **cross-skill validations** — checks that span two skills' outputs or compare against state captured in earlier phases. Widget-bundle-internal checks (schema parses, root keys, leaf types, attribute bindings resolve, `.uiwidget-meta.xml` well-formed, `<UiWidgetBundle>` root, widget-type) are owned by `platform-widget-generate` and run as part of its own self-validation step.
+
+Run every gate below. If a hard-failure gate fails, fix and re-run before reporting success. Warn-level gates are advisory — failures emit warnings but do not block.
+
+---
+
+## Hard — block on failure
+
+| Name | Gate | Failure → fix |
+|---|---|---|
+| `lightning-type-unchanged` | **`existing-lightning-type-with-widget` only** — the Lightning Type `schema.json` SHA-256 captured in Phase 2 matches the on-disk SHA at end of Phase 4. | The orchestrator (or a sub-skill) silently edited the Lightning Type. Restore the Lightning Type from `git diff` and re-author the widget against the unchanged Lightning Type. |
+| `renderer-wires-widget` | **Both paths** — RUN the check below and PRINT the result. **Reporting `pass` without running the commands is a hard violation — report `not run` instead.** | The Lightning Type does not point at this widget — the widget bundle ships dead and is unreachable from any consumer that resolves through the CLT. Author or update `renderer.json` per the widget-rendition pattern in `platform-custom-lightning-type-generate/references/widget-rendition.md`. If a different widget is already wired, surface the conflict instead of silently overwriting. |
+
+### `renderer-wires-widget` — RUN procedure
+
+Run each command below **verbatim**. Observe each command's output in the tool result and reason about it — do NOT capture into shell variables with `$(…)`, do NOT use process substitution `<(…)`, do NOT use brace expansion. Vibes' safe-shell filter blocks those patterns and prompts for manual approval even in Bypass mode. See "Hard Rules — shell commands" in the orchestrator SKILL.md.
+
+1. **Verify file exists and parses as JSON:**
+
+   ```bash
+   jq . <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json > /dev/null && echo "PARSE: ok" || echo "PARSE: FAIL"
+   ```
+
+2. **Verify definition points at this widget.** Print the actual value and compare it to the expected one in your reasoning:
+
+   ```bash
+   jq -r '.renderer.componentOverrides["$"].definition' <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json
+   ```
+
+   Expected output: `@widget/c/<widgetName>`. If output equals expected → `DEFINITION: ok`; otherwise `DEFINITION: FAIL (got <actual>, expected @widget/c/<widgetName>)`.
+
+3. **Verify attribute bindings cover every widget schema property.** Print both key lists with separate commands; compare them in your reasoning (do NOT `diff` with process substitution):
+
+   ```bash
+   echo "SCHEMA_KEYS (expected):"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+   ```bash
+   echo "RENDERER_KEYS (actual):"
+   jq -r '.renderer.componentOverrides["$"].attributes | keys[]' <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json | sort -u
+   ```
+
+   Classify: same set → `ATTRIBUTES: ok`. Keys in `SCHEMA_KEYS` not in `RENDERER_KEYS` → `ATTRIBUTES: FAIL (missing: <list>)`. Keys in `RENDERER_KEYS` not in `SCHEMA_KEYS` → `ATTRIBUTES: FAIL (extra: <list>)`.
+
+4. **Verify each attribute value is a well-formed binding.** Dump the attributes map and inspect each entry in your reasoning:
+
+   ```bash
+   jq '.renderer.componentOverrides["$"].attributes' <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json
+   ```
+
+   For every key `K`, the value must match `{!$attrs.K}` exactly (same key name, no whitespace). All match → `BINDINGS: ok`. Otherwise `BINDINGS: FAIL (<key>: got <value>, expected {!$attrs.<key>})` for each offender.
+
+5. **Result classification:**
+   - All checks pass → `pass`
+   - File missing or does not parse → `fail (renderer.json missing or invalid JSON)`
+   - Definition mismatch → `fail (definition does not point at widget: got <actual>)`
+   - Attribute coverage mismatch → `fail (missing bindings: <list>)` or `fail (extra bindings: <list>)`
+   - Binding format invalid → `fail (malformed binding for <key>: <actual>)`
+
+---
+
+## Warn — advisory
+
+| Name | Gate | Warning meaning |
+|---|---|---|
+| `field-trace` | **Both paths** — RUN the trace below and PRINT both lists explicitly. | See "`field-trace` — RUN procedure" below. **Reporting `pass` without printing the two lists side by side is a hard violation — report `not run` instead.** |
+| `deploy-check` | **`new-lightning-type-with-widget` only** — RUN `sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName>` and report the result. | Apex / Custom Lightning Type references are unresolved when validated against the org. Common cause: the FQN in the Custom Lightning Type does not match the actual Apex class. **Reporting `pass` without running this command is a hard violation. Reporting `not run` is only valid if the source files do not exist in the local project — "not yet deployed" is not a valid reason; `--check-only` submits the source as part of the call.** |
+
+### `field-trace` — RUN procedure
+
+The gate enforces two things: no invented widget fields (subset rule), and no silent omission of `@AuraEnabled` fields (omission must be in the build plan's `Properties omitted:` and approved at Phase 3).
+
+**`APEX_FIELDS` and `WIDGET_PROPS` are labels in the printed output, NOT shell variables. Do NOT assign either with `APEX_FIELDS=$(grep …)` or `WIDGET_PROPS=$(jq …)` — Vibes' safe-shell filter blocks `$(…)` and stalls the eval on manual approval. Run each command bare and reason about the output.**
+
+1. **Resolve the payload class from the Apex class FQN**, then extract `@AuraEnabled` field names from the payload class **and from every inner class referenced by it** — both singular nested objects (e.g. `Address address`) and `List<InnerClass>` collections. Split the FQN on `$`: no `$` → the outer class is the payload; with `$` (e.g. `c__OrderResponses$CreateResult`) → the named inner class is the payload and the outer class's own `@AuraEnabled` fields are NOT part of the trace.
+
+   Read the outer `.cls` file at `<pkgDir>/classes/<ClassName>.cls`; when the payload is the outer class, grep the whole file; when the payload is an inner class, scope the grep to that inner class's block.
+
+   ```bash
+   # Outer-class payload — print the field names. Do NOT wrap in $().
+   echo "APEX_FIELDS:"
+   grep -B0 -A2 '@AuraEnabled' <pkgDir>/classes/<ClassName>.cls \
+     | grep -oE '(public|global)\s+[A-Za-z0-9_<>,\s]+\s+[a-zA-Z_][a-zA-Z0-9_]*\s*;' \
+     | sed -E 's/.*\s([a-zA-Z_][a-zA-Z0-9_]*)\s*;/\1/' \
+     | sort -u
+   ```
+
+   For an inner-class payload, read the .cls file, locate the named inner class's block (`class <InnerClass> {…}`), and run the field enumeration scoped to that block only. Identify further inner classes the payload class declares (singular `InnerClass <field>;` and `List<InnerClass> <field>;`) — typically siblings inside the same outer file — and repeat against each. Combine the printed sets in your reasoning under the label `APEX_FIELDS`. If grep returns nothing, fall back to reading the .cls file with the Read tool and listing fields manually — but do NOT skip the comparison.
+
+2. Extract widget schema property keys, expanding nested `lightning__objectType` properties to their inner-field dot paths:
+
+   ```bash
+   echo "WIDGET_PROPS:"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+   For any property whose `lightning:type` is `lightning__objectType`, also include the dot-notation bindings actually referenced in the widget body (e.g. `address.city`) — you can see these by reading the widget JSON directly with the Read tool. For any property whose `lightning:type` is `lightning__listType`, also include the `{!$item.<innerField>}` references inside the `forEach`. Combine in your reasoning under the label `WIDGET_PROPS`.
+
+3. PRINT both lists in the gate report (not just an assertion) — as plain text you author from the two command outputs above, NOT via a shell expression:
+
+   ```text
+   APEX_FIELDS:  cartId, currencyIsoCode, items.itemId, items.qty, itemCount, ...
+   WIDGET_PROPS: cartId, currencyIsoCode, itemCount, ...
+   INVENTED  (widget − apex): <empty>
+   OMITTED   (apex − widget): items.*
+   ```
+
+4. Result classification:
+   - `INVENTED` non-empty → **fail** (subset rule violated). Report `fail (invented: <list>)`.
+   - `OMITTED` non-empty AND every omitted field appears in the Phase 3 build plan's `Properties omitted:` section → **pass** (auditable omission).
+   - `OMITTED` non-empty AND any omitted field is NOT in `Properties omitted:` → **warn** (silent omission). Report `warn (silent omission: <list>)` and surface to the user before the final summary.
+   - Both empty → **pass**.
+
+---
+
+## Direction of subset rule
+
+The widget `schema.json` (plus the dot-notation paths it binds through nested `lightning__objectType` properties and the `{!$item.X}` references inside `lightning__listType` loops) is a **subset** of the Apex class's `@AuraEnabled` fields (outer class plus every referenced inner class). The orchestrator enforces both directions, asymmetrically:
+
+- **No invented fields (hard).** Widget MUST NOT introduce properties or inner-field paths the Apex classes do not expose. A non-empty INVENTED set fails `field-trace`.
+- **No silent omissions (warn).** Widget MAY omit Apex fields, but every omission MUST appear in the Phase 3 build plan's `Properties omitted:` section with a rationale. Omissions not in the plan are silent and warn at `field-trace` (OMITTED list flagged). The leaf skill must surface the proposed omissions to the user before authoring (`platform-widget-generate/references/schema-from-lightning-type.md`). Inner-class fields (whether reached as singular nested objects or via `List<InnerClass>`) are NEVER silently omitted.
+
+---
+
+## Reporting
+
+Phase 6 must list each gate's result by name: `pass`, `fail (<reason>)`, `warn (<reason>)`, or `not run`. Do not summarize ("all passed") — list each gate explicitly so the reviewer can spot a silent skip.

package/skills/platform-sharing-owd-configure/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: platform-sharing-owd-configure
+description: "Use when the user wants to retrieve or update Organization-Wide Default (OWD) sharing settings for Salesforce objects. TRIGGER when: user asks to check current OWD settings, view sharing defaults, change default access levels (Private, Public Read Only, Public Read/Write, Controlled by Parent), configure internal or external access for standard or custom objects, mentions org-wide defaults, wants to make records private or restrict who can see records, wants to control default record visibility for an object, or references .settings-meta.xml sharing fields or sharingModel in .object-meta.xml files. DO NOT TRIGGER when: user asks about sharing rules, criteria-based sharing, role hierarchy, or manual sharing — delegate to platform-sharing-rules-generate."
+metadata:
+  version: "1.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Managing Org-Wide Defaults
+
+Retrieve and update Organization-Wide Default (OWD) sharing settings for standard and custom objects in a Salesforce org. OWDs define the baseline level of access users have to records they do not own.
+
+## Scope
+
+- **In scope**: Retrieving current OWD settings, updating internal/external access levels for standard and custom objects
+- **Out of scope**: Sharing rules, role hierarchy configuration, manual sharing, permission sets, criteria-based sharing — delegate to appropriate skills
+
+---
+
+## Clarifying Questions
+
+Before proceeding, confirm with the user if not already clear:
+
+- Which object(s) do you want to get or update OWD settings for?
+- What access level do you want to set? (Private, Public Read Only, Public Read/Write, Controlled by Parent)
+- Do you need to change both internal and external access, or just one?
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Target org**: The org alias or username to query/update (use default org if not specified)
+- **Object name(s)**: Standard object API name (e.g., `Account`, `Contact`) or custom object API name (e.g., `Invoice__c`)
+- **Operation**: Get (retrieve current settings) or Update (change access levels)
+- **Access levels** (for update): Internal access and/or external access values
+
+Defaults unless specified:
+- Use the default connected org
+- If only one access level is provided, assume it applies to internal access
+
+---
+
+## Workflow
+
+All steps are sequential. Do not skip or reorder.
+
+### Phase 1 — Retrieve Current Settings
+
+1. **Query current OWD settings** using the Salesforce CLI Tooling API:
+   ```bash
+   sf data query --query "SELECT QualifiedApiName, InternalSharingModel, ExternalSharingModel FROM EntityDefinition WHERE QualifiedApiName = '<ObjectName>'" --use-tooling-api --target-org <org>
+   ```
+
+2. **For retrieving all OWD settings at once:**
+   ```bash
+   sf data query --query "SELECT QualifiedApiName, InternalSharingModel, ExternalSharingModel FROM EntityDefinition WHERE IsCustomizable = true ORDER BY QualifiedApiName" --use-tooling-api --target-org <org>
+   ```
+
+3. **Present results clearly** — read `references/access_levels.md` for valid values and display a formatted table to the user.
+
+### Phase 2 — Update Settings (if requested)
+
+4. **Validate the requested access level** — read `references/access_levels.md` to confirm the value is valid for the target object.
+
+5. **Retrieve the object metadata** using the Metadata API (same command for both standard and custom objects):
+   ```bash
+   sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>
+   ```
+   This retrieves `<ObjectName>.object-meta.xml` containing `<sharingModel>` and `<externalSharingModel>`. See `references/metadata_api_approach.md` for the full procedure.
+
+6. **Modify the sharing settings** — update the `<sharingModel>` (internal access) and/or `<externalSharingModel>` (external access) in the object's `.object-meta.xml`. Read `references/metadata_api_approach.md` for details.
+
+7. **Pre-deploy verification** — before deploying, confirm:
+   - [ ] External access is not more permissive than internal access
+   - [ ] Objects with Master-Detail relationships use `ControlledByParent`
+   - [ ] The requested access level is valid for the target object (see `references/access_levels.md`)
+   - [ ] Cross-object constraints are satisfied (see "Cross-Object Constraints" in `references/access_levels.md`)
+
+8. **Deploy the updated settings:**
+   ```bash
+   sf project deploy start --metadata CustomObject:<ObjectName> --target-org <org>
+   ```
+
+9. **Verify the change** by re-running the query from Step 1.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Objects with Master-Detail relationships must use `ControlledByParent` | Platform enforces this — attempting other values fails |
+| External access cannot be more permissive than internal access | Salesforce rejects configurations where external > internal |
+| Some standard objects have fixed OWD (e.g., User, Activity) | Not all objects support OWD changes |
+| Changing OWD to more restrictive triggers sharing recalculation | This can take significant time on large orgs — warn the user |
+| Custom objects default to `Public Read/Write` when created | Users may not realize the default is permissive |
+| Always verify the org connection before querying | Prevents confusing error messages |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `INSUFFICIENT_ACCESS` error when updating | User needs Manage Sharing permission or System Administrator profile |
+| OWD change appears stuck | Sharing recalculation is running — check Setup > Sharing Settings for progress |
+| Custom object not found in query | Use the full API name including `__c` suffix |
+| `ControlledByParent` not available | Object has no Master-Detail relationship — use Private, Public Read Only, or Public Read/Write |
+| External access field not showing | External sharing model only appears when external org-wide defaults are enabled |
+| Query returns no results | Object may not be customizable or API name may be incorrect — verify spelling |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- **For get operations**: Formatted table showing object name, internal access level, and external access level
+- **For update operations**: Confirmation of the change with before/after comparison
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Creating sharing rules after restricting OWD | `platform-sharing-rules-generate` skill |
+| Deploying metadata changes to another org | `platform-metadata-deploy` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/access_levels.md` | When validating or explaining OWD access level values |
+| `references/metadata_api_approach.md` | When using Metadata API to update OWD instead of Tooling API |
+| `examples/get_owd_output.md` | To verify formatted output matches expected structure |
+| `examples/update_owd_output.md` | To verify update confirmation matches expected structure |

package/skills/platform-sharing-owd-configure/examples/get_owd_output.md

@@ -0,0 +1,38 @@
+# Example: Get OWD Output
+
+## Single Object Query
+
+**User prompt:** "What are the org-wide defaults for Account?"
+
+**Expected output format:**
+
+| Object | Internal Access | External Access |
+|--------|----------------|-----------------|
+| Account | Public Read/Write | Private |
+
+## Multiple Objects Query
+
+**User prompt:** "Show me all org-wide defaults"
+
+**Expected output format:**
+
+| Object | Internal Access | External Access |
+|--------|----------------|-----------------|
+| Account | Public Read/Write | Private |
+| Contact | Controlled by Parent | Controlled by Parent |
+| Opportunity | Private | Private |
+| Case | Public Read/Write/Transfer | Private |
+| Lead | Public Read/Write/Transfer | Public Read Only |
+| Campaign | Public Full Access | Private |
+| Invoice__c | Private | Private |
+| Project__c | Public Read Only | Private |
+
+## Custom Object Query
+
+**User prompt:** "Get the OWD for Invoice__c"
+
+**Expected output format:**
+
+| Object | Internal Access | External Access |
+|--------|----------------|-----------------|
+| Invoice__c | Private | Private |

package/skills/platform-sharing-owd-configure/examples/update_owd_output.md

@@ -0,0 +1,44 @@
+# Example: Update OWD Output
+
+## Standard Object Update
+
+**User prompt:** "Change Account OWD to Private"
+
+**Expected output format:**
+
+### OWD Updated Successfully
+
+| Object | Field | Before | After |
+|--------|-------|--------|-------|
+| Account | Internal Access | Public Read/Write | Private |
+| Account | External Access | Private | Private |
+
+> **Note:** Sharing recalculation has been triggered. This may take time on large orgs. Check Setup > Sharing Settings to monitor progress.
+
+## Custom Object Update
+
+**User prompt:** "Set Invoice__c org-wide default to Public Read Only for internal and Private for external"
+
+**Expected output format:**
+
+### OWD Updated Successfully
+
+| Object | Field | Before | After |
+|--------|-------|--------|-------|
+| Invoice__c | Internal Access | Private | Public Read Only |
+| Invoice__c | External Access | Private | Private |
+
+## Update with Warning
+
+**User prompt:** "Change Opportunity OWD to Public Read/Write"
+
+**Expected output format:**
+
+### OWD Updated Successfully
+
+| Object | Field | Before | After |
+|--------|-------|--------|-------|
+| Opportunity | Internal Access | Private | Public Read/Write |
+| Opportunity | External Access | Private | Private |
+
+> **Warning:** Opening access from Private to Public Read/Write means all users will be able to view and edit all Opportunity records regardless of ownership. Ensure this aligns with your security requirements.

package/skills/platform-sharing-owd-configure/references/access_levels.md

@@ -0,0 +1,49 @@
+# OWD Access Levels Reference
+
+## Valid Access Level Values
+
+| API Value | Display Name | Description |
+|-----------|-------------|-------------|
+| `Private` | Private | Only record owner and users above in role hierarchy can view/edit |
+| `Read` | Public Read Only | All users can view records but only owner can edit |
+| `ReadWrite` | Public Read/Write | All users can view and edit all records |
+| `ReadWriteTransfer` | Public Read/Write/Transfer | All users can view, edit, and transfer ownership (Cases, Leads only) |
+| `FullAccess` | Public Full Access | All users have full access including delete (Campaigns only) |
+| `ControlledByParent` | Controlled by Parent | Access determined by parent record's sharing (requires Master-Detail) |
+
+## Object-Specific Restrictions
+
+| Object | Allowed Values | Notes |
+|--------|---------------|-------|
+| Account | Private, Read, ReadWrite | Contact and Opportunity OWD tied to Account when ControlledByParent |
+| Contact | Private, Read, ReadWrite, ControlledByParent | ControlledByParent ties to Account |
+| Opportunity | Private, Read, ReadWrite, ControlledByParent | ControlledByParent ties to Account |
+| Case | Private, Read, ReadWrite, ReadWriteTransfer | Transfer is unique to Case |
+| Lead | Private, Read, ReadWrite, ReadWriteTransfer | Transfer is unique to Lead |
+| Campaign | Private, Read, ReadWrite, FullAccess | FullAccess is unique to Campaign |
+| Custom Objects | Private, Read, ReadWrite, ControlledByParent | ControlledByParent requires Master-Detail field |
+
+## Cross-Object Constraints
+
+| Constraint | Detail |
+|-----------|--------|
+| Account = Private cascades | Setting Account to Private forces Contact, Case, and Opportunity to Private — all four recalculate together |
+| Contract tied to Account | Contract OWD cannot be set independently; it follows Account's OWD |
+| Pricebook | Only accepts `Use` or `No Access` (`ReadSelect` / `None` in API) — standard access levels do not apply |
+| ControlledByParent cascade | If a child object uses ControlledByParent, changing the parent's OWD implicitly changes the child's effective access |
+
+## Internal vs External Access
+
+- **Internal access**: Applies to users within the org (internal users)
+- **External access**: Applies to external users (Community/Experience Cloud users, portal users)
+- External access can never be more permissive than internal access
+- External OWD must be enabled in Setup before external values appear
+
+## Common Transitions
+
+| From | To | Impact |
+|------|-----|--------|
+| Public Read/Write → Private | High | Triggers full sharing recalculation; users lose access immediately |
+| Private → Public Read Only | Medium | Grants read access to all; recalculation needed |
+| Private → Public Read/Write | Low | Opens access broadly; fast operation |
+| Any → ControlledByParent | High | Requires Master-Detail relationship; existing sharing rules deleted |

package/skills/platform-sharing-owd-configure/references/metadata_api_approach.md

@@ -0,0 +1,69 @@
+# Metadata API Approach for Updating OWD
+
+When the Tooling API approach is not suitable or the user prefers a metadata-driven workflow, use the Metadata API to update Organization-Wide Defaults.
+
+## Step-by-Step Procedure
+
+### 1. Create a project directory (if not already in an SFDX project)
+
+```bash
+sf project generate --name owd-update --template empty
+cd owd-update
+```
+
+### 2. Retrieve the object metadata
+
+Both standard and custom objects store their OWD sharing model in `<Object>.object-meta.xml` using the `<sharingModel>` and `<externalSharingModel>` elements.
+
+```bash
+sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>
+```
+
+This creates a file at: `force-app/main/default/objects/<ObjectName>/<ObjectName>.object-meta.xml`
+
+### 3. Locate the sharing model entries
+
+The object metadata file contains `<sharingModel>` and `<externalSharingModel>` elements:
+
+Example for a standard object (Account):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <sharingModel>ReadWrite</sharingModel>
+    <externalSharingModel>Private</externalSharingModel>
+</CustomObject>
+```
+
+Example for a custom object (Invoice__c):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Invoice</label>
+    <sharingModel>Private</sharingModel>
+    <externalSharingModel>Private</externalSharingModel>
+</CustomObject>
+```
+
+### 4. Modify the sharing model values
+
+Update the `<sharingModel>` (internal access) and/or `<externalSharingModel>` (external access) to the desired access level. See `access_levels.md` for valid values per object.
+
+### 5. Deploy the changes
+
+```bash
+sf project deploy start --metadata CustomObject:<ObjectName> --target-org <org>
+```
+
+### 6. Verify
+
+Re-query using the Tooling API to confirm the change took effect:
+```bash
+sf data query --query "SELECT QualifiedApiName, InternalSharingModel, ExternalSharingModel FROM EntityDefinition WHERE QualifiedApiName = '<ObjectName>'" --use-tooling-api --target-org <org>
+```
+
+## When to Use This Approach
+
+- User wants a source-trackable, version-controlled change
+- Multiple OWD changes need to be deployed together
+- Change is part of a larger metadata deployment
+- Tooling API direct update is not permitted by org policies