--network-file <sourceRoot>/networks/<site>.network-meta.xml \
 --target-org <org> --site <site> --deploy

**Best-effort:** the helper exits **0** on success or already-set, and **3** on a
recoverable skip (network file missing, origin unresolvable, XML-special char, or
deploy failure). Treat **exit 3 as a loud skip, not a setup failure** — continue
the rest of setup and tell the user to set the logout URL manually in the site's
Administration settings. Usage, exit-code contract, and port-provenance:
`references/logout-url.md`.

## Step 4 — Assign permission sets

Discover permission sets under `<packageDir>/main/default/permissionsets/`. If
none exist and none were passed explicitly, skip.

**If permsets exist but `org-setup.config.json` is missing, do NOT silently
skip.** A missing config makes every discovered permset resolve to `skip`, so
nothing gets assigned and the later GraphQL schema comes back incomplete (the
caller lacks FLS). Instead, help the user supply the assignments — either scaffold
`org-setup.config.json` from `assets/org-setup.config.template.json` or gather the
per-permset assignee inputs for a one-off run. Full schema + scaffolding flow:
`references/config-scaffold.md`. Confirm intent before writing the file or
assigning — don't fabricate assignees.

Otherwise assign each per its config assignee (`org-setup.config.json` →
`permsetAssignments`), where each assignee is one of `currentUser`, `guestUser`,
or `skip` (default `skip`):

```bash
sf org assign permset --name <permset> --target-org <org> [--on-behalf-of <guestUsername>]

• currentUser — omit --on-behalf-of.
• guestUser — resolve the site's guest username first (see the guest-user section in references/self-registration.md). If the site can't be derived or no guest user resolves, skip that permset and record the reason — don't abort the others.
• Treat "Duplicate … PermissionSet" and "not found … target org" as skips, not failures.

Required so GraphQL introspection returns the correct schema (the caller needs FLS on custom fields).

Step 5 — Assign role (config-gated)

Run only when org-setup.config.json has role: { assignee: "currentUser", roleName: "<UserRole>" }. Assigning a role to the current user is what lets Experience Cloud self-registration work. Idempotent — skip if the user already has a role. Detail + exact queries: references/role-assignment.md.

Step 6 — Enable self-registration (config-gated) — ask first

Run only when org-setup.config.json has selfRegistration: { selfRegProfile, accountName }. Ask the user before running. Sequence (full detail in references/self-registration.md):

1. License pre-check (soft skip) — if the org lacks a seat on the profile's license, warn and skip; it is not a failure. See references/license-checks.md.
2. Derive the site — run scripts/derive-site-name.sh; it outputs the site name (the base name of the single *.network-meta.xml) or exits non-zero when zero or more than one exist (ambiguous — stop).
3. Flip self-reg on + redeploy the network file — apply Edit B of assets/network-selfreg-xml-recipe.md (set selfRegistration=true, inject <selfRegProfile>), then redeploy only that one file. Idempotent — skip both if already enabled. (Edit A, the member-group add, already happened in step 3.)
4. Create the Account + NetworkSelfRegistration — apply assets/network-selfreg.apex (idempotent; both are query-then-create; run 4a and 4b as two separate sf apex run invocations).

Step 6b — Enable social login (config-gated)

Run only when org-setup.config.json has a socialLogin block. If the block is absent, loadSocialLoginConfig returns null and the step is hidden — no-op cleanly and say so. This step is non-destructive and idempotent (it only adds missing links/members), so — unlike self-registration and data import — it does not require asking first.

This links the site's configured Auth Providers (OAuth) and SAML SSO configs to the site so the built-in Social Login component renders their buttons on the React login page. On React (Site Container) sites the SSO admin UI is hidden, so the linking is done programmatically via AuthConfig / AuthConfigProviders records — you cannot do it by clicking through Setup. Full detail, sub-steps, and port-provenance: references/social-login.md.

Config shape (see references/config-scaffold.md for the full schema):

{ "socialLogin": {
    "communityMemberProfile": "Customer Community User",
    "authProviderNames": ["Google", "My_SAML_Provider"],
    "communityUserPermset": "myapp_Guest_User_Api_Access"
} }

Sequence (mirrors reference org-setup.mjs main() social-login step, which runs after self-registration and before the data/GraphQL steps):

Apply the assets/ templates verbatim (like the self-reg/data steps) — full runnable commands for each sub-step are in references/social-login.md:

1. Derive the site — run scripts/derive-site-name.sh (single *.network-meta.xml; stop if zero/ambiguous). Social login needs the site to resolve its AuthConfig.
2. Enable "Allow standard external profiles" — deploy assets/Communities.settings-meta.xml via Metadata API (from a throwaway minimal project; see the reference). Required so the SSO registration handler can create users on standard community profiles; without it auth providers fail user insert with FIELD_INTEGRITY_EXCEPTION. A "already active" warning is a non-fatal skip.
3. Link Auth Providers to the site AuthConfig — run assets/social-login-auth-providers.apex verbatim (substitute <siteName>, <ProviderNamesList>, <ApiVersion>) to create the missing AuthConfigProviders junctions, then read its |DEBUG| lines (table in the reference). All-or-nothing: if any configured authProviderNames entry has no matching AuthProvider (OAuth) or SamlSsoConfig (SAML) record, it emits MISSING_PROVIDERS and links nothing — create/fix them in Setup first. Already-linked providers are skipped (idempotent).
4. Add the community member profile to NetworkMemberGroup — resolve the Network + Profile Ids and create the membership if absent (sf data commands in the reference). Without it, SSO-registered users hit NO_ACCESS: User was not authorized for the community.
5. (Optional) Assign communityUserPermset to community users — only when configured. Grants ApiEnabled so getCurrentUser() (/chatter/users/me) works for SSO-created users.

IMPORTANT: A socialLogin block present but skipped is a silent-failure trap — the app deploys fine, but no social-login buttons ever appear on the login page and there is no error explaining why. Do not silently skip: run the step when the block is present, or state clearly that it was absent.

Step 7 — Data import (presence-driven) — ask first

Run scripts/find-data-plan.sh first. If it exits non-zero, skip this step — do not prompt and do not error; just move on to step 8 (a brief "no data plan, skipping data import" note is fine). There is nothing to import without a plan. On success it prints the plan's path (it searches recursively, so both a project-root data/ and a <packageDir>/main/default/data/ layout resolve).

When it exists: always ask the user before importing or cleaning data — it deletes existing records first. Apply the verbatim templates; do not improvise Apex:

1. Run scripts/find-prep-script.sh. If it succeeds, it prints the path of a prepare-import-unique-fields.js that ships with the app — run that first; it deduplicates re-runs by stamping stable unique keys on the record files. Invoke it the way that copy expects (its interface varies — see references/data-import.md). If it exits non-zero, there is no prep script — skip to the clean step.
2. Clean in reverse plan order (children before parents) with assets/data-delete.apex.
3. Import in forward plan order with assets/data-import.apex, resolving @referenceId refs and batching by measured size.

Protocol, @referenceId resolution, measured batching, and the SETUP_RESULT_JSON parse-and-hard-fail rule: references/data-import.md.

Step 8 — GraphQL schema fetch + codegen

Run from the UI bundle directory, after deploy and permission assignment (the schema reflects org state and the caller's FLS):

npm install
SF_TARGET_ORG=<org> npm run graphql:schema
npm run graphql:codegen
npm run build

Detail: references/graphql.md. Re-run schema fetch + codegen after every deploy that changes objects, fields, or permissions.

Done

Setup ends here — the steps above (including the config-gated 6b social login) are the complete sequence. Local dev preview (npm run dev:preview) is a separate developer action, not part of setup; if the user asks to preview the site, see references/dev-preview.md.

Critical rules

• Deploy metadata before fetching schema — custom objects/fields appear only after deploy.
• Assign permissions before schema fetch — the caller may lack FLS otherwise.
• Re-run schema fetch + codegen after every metadata deploy that changes objects, fields, or permissions.
• Never silently skip permission assignment, self-registration, social login, or data import — either the convention file/config block is present (run it, asking first for the destructive ones) or it's absent (skip cleanly and say so). A present-but-skipped socialLogin block means no login buttons appear with no error to explain it.
• Discover the source path from sfdx-project.json; never hardcode force-app/main/default.
• Apply the assets/ Apex and XML templates verbatim — they encode duplicate-rule bypass, allOrNone=false deletes, idempotency, SOQL-safety, and (for social login) the all-or-nothing provider pre-check and the DML-not-allowed-on-AuthConfigProviders REST-callout insert — all easy to get wrong by hand.

Interaction order (summary)

1. Authenticate org
2. Build UI bundles (pre-deploy)
3. Deploy metadata (deploy-license gate if self-reg configured) 3b. Set the site logout URL (if logoutUrl configured — post-deploy, idempotent, best-effort)
4. Assign permission sets (config-driven assignee)
5. Assign role (if configured)
6. Enable self-registration (if configured — ask first) 6b. Enable social login (if socialLogin configured — idempotent, no ask needed)
7. Import data (if data plan exists — ask first)
8. Fetch GraphQL schema + codegen + final build