afv-library/skills/experience-ui-bundle-deploy/references/config-scaffold.md

org-setup.config.json — schema and scaffolding when it's missing

org-setup.config.json (at the project root) drives three steps: permission-set assignment (step 4), role assignment (step 5), and self-registration (step 6). Source of truth for the schema: reference org-setup-config-schema.mjs (zod .strict() — unknown keys are rejected); consumption: loadPermsetConfig / resolveAssignment (org-setup.mjs 464-478).

Why a missing file is a trap for the permset step

When the file is absent, loadPermsetConfig returns { defaultAssignee: 'skip', assignments: {} } (org-setup.mjs 466), so every permission set discovered under permissionsets/ resolves to skip and is silently not assigned. The deploy looks successful, but GraphQL introspection (step 8) then returns an incomplete schema because the caller lacks FLS.

So: permset folder present + config file absent = help the user create the config (or gather equivalent inputs) rather than silently skipping. Do not fabricate assignments — confirm intent first (see below).

Full schema

Every top-level key is optional; each object is strict (no extra keys).

{
  "permsetAssignments": {
    "defaultAssignee": "currentUser | guestUser | skip",
    "assignments": {
      "<PermissionSetApiName>": { "assignee": "currentUser | guestUser | skip" }
    }
  },
  "role": { "assignee": "currentUser", "roleName": "<UserRole name>" },
  "selfRegistration": { "selfRegProfile": "<Profile API name>",
                        "accountName": "<display name>" }
}

• assignee is a closed set: currentUser, guestUser, or skip — never a raw username. defaultAssignee applies to any discovered permset not named in assignments; it defaults to skip when the permsetAssignments block is present but omits it.
• No siteName anywhere — for guestUser the site is derived from the single networks/<siteName>.network-meta.xml the app ships. If the assignee is guestUser and the site can't be derived or the guest user can't be resolved, that permset is skipped and recorded, not fatal (see step 4).
• role.assignee must be currentUser (the only value the flow honors); roleName is a non-empty UserRole name.
• selfRegistration has no license field — the required license is derived from selfRegProfile (see references/license-checks.md).

Scaffolding flow (permset folder present, config missing)

1. List the permission sets under <packageDir>/main/default/permissionsets/ (their file base names are the API names) so the choice is concrete.
2. Ask the user, per permset, who to assign it to — currentUser, guestUser, or skip. Default a whole-set answer to currentUser (not skip) since the folder exists on purpose; only use guestUser for permsets meant for the site's guest user. Also ask whether they want a role and/or selfRegistration block while you're writing the file (both optional).
3. Offer two equivalent paths — let the user pick:
   • Write the file: copy assets/org-setup.config.template.json to org-setup.config.json at the project root and fill in the answers. This is durable — re-runs and the reference npm run setup both read it.
   • One-off inputs: if they don't want a file, treat their answers as the config for this run only (assign each permset per the stated assignee via step 4's sf org assign permset command). Nothing persists.
4. Validate before relying on it: keys must match the strict schema exactly (e.g. it's permsetAssignments, not the singular permsetAssignment), and assignee values must be one of the three literals. Reject anything else and re-ask rather than writing an invalid file.

Prefer writing the file when the user is unsure — it makes the behavior reproducible and matches what the reference tooling expects.