create-webroles

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# Create Web Roles

Create web roles for a Power Pages code site. Web roles define the permissions and access levels for different types of site users.

## Core Principles

- **Use TaskCreate/TaskUpdate**: Track all progress throughout all phases — create the todo list upfront with all phases before starting any work.
- **Always use the UUID script**: Never generate UUIDs manually — always use `${PLUGIN_ROOT}/scripts/generate-uuid.js` to produce valid UUID v4 values for each web role.
- **Preserve uniqueness constraints**: Only one role can have `anonymoususersrole: true` and only one can have `authenticatedusersrole: true`. Always check existing roles before setting these flags.
- **Caller-suppress mode is opt-in**: When invoked by another skill (e.g. `/add-ai-webapi`) with the `[CALLED-BY-PARENT-SKILL]` sentinel in `$ARGUMENTS`, suppress this skill's deploy prompts (Phase 1's missing-deploy ask, Phase 6's deploy ask (step 3), and the closing reminder) and return as soon as roles are created. The caller batches the deploy at end-of-orchestration. Human invocations never trigger this mode. See Phase 0 below for parsing.

> **Prerequisite:** The site must be deployed at least once before web roles can be created, since deployment creates the `.powerpages-site` folder structure that stores web role definitions.

**Initial request:** $ARGUMENTS

## Phase 0: Detect caller-suppress mode

Inspect `$ARGUMENTS`. If the text contains the sentinel `[CALLED-BY-PARENT-SKILL]`, set an
internal flag **caller-suppress = true** that downstream phases consult. The optional token
`caller=<skill-name>` may follow the sentinel for diagnostic purposes (e.g.
`caller=add-ai-webapi`); record it for the final summary but do not branch on it.

When the flag is set, skip every deploy prompt this skill would otherwise issue:

- **Phase 1 missing-deploy ask**: if `.powerpages-site` is absent, do NOT ask the user to
  deploy now. Stop with a clear contract-violation message back to the caller — the caller
  was supposed to gate on this before invoking us.
- **Phase 6 deploy ask (step 3)** and the closing "Please run `/deploy-site`"
  reminder: skip both. The caller batches the single deploy decision at end-of-orchestration.

When the sentinel is absent, proceed exactly as today (full interactive flow). This is the
regression guard — no human invocation changes behavior.

---

## Workflow

1. **Phase 1: Verify Site Structure** → Check for `.powerpages-site/web-roles/` directory
2. **Phase 2: Discover Existing Roles** → Read current web role YAML files
3. **Phase 3: Determine New Roles** → Analyze the site and ask the user what roles are needed
4. **Phase 4: Create Web Role Files** → Generate YAML files with UUIDs from the Node script
5. **Phase 5: Verify Web Roles** → Validate all created files exist, have valid UUIDs, and flags are correct
6. **Phase 6: Review & Deploy** → Present summary and proceed to deployment

---

## Phase 1: Verify Site Structure

**Goal**: Confirm the `.powerpages-site/web-roles/` directory exists and is ready for web role files

**Actions**:

1. Locate the project root (`**/powerpages.config.json`) and check for `.powerpages-site/web-roles/`.

<!-- gate: create-webroles:1.deploy-first | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · create-webroles:1.deploy-first):** `.powerpages-site` missing — skill cannot proceed without that folder. Prompt to deploy first or stop.
>
> **Trigger:** Phase 1 found no `.powerpages-site` directory.
> **Why we ask:** Web role YAML files written to a non-existent path will never get picked up by deploy; user thinks roles were created but they weren't.
> **Cancel leaves:** Nothing — no YAML files written.

2. **If `.powerpages-site` does NOT exist:**
   - **In caller-suppress mode** (Phase 0 flag): stop with a contract-violation message —
     the calling skill should have gated on this folder existing before invoking us.
   - **Otherwise**: ask the user to deploy first via `AskUserQuestion` (options: "Yes, deploy now (Recommended)", "No, I'll do it later"). If yes, invoke `/deploy-site` then resume from Phase 2. If no, stop.

3. **If `.powerpages-site` exists but `web-roles/` does NOT:** Create the `<PROJECT_ROOT>/.powerpages-site/web-roles/` directory.

4. **If both exist:** Proceed to Phase 2.

**Output**: Confirmed `.powerpages-site/web-roles/` directory exists and is ready

---

## Phase 2: Discover Existing Roles

**Goal**: Identify all web roles already defined for the site

**Actions**:

1. Read all YAML files in the `.powerpages-site/web-roles/` directory. Each file represents one web role with this format:

   ```yaml
   anonymoususersrole: false
   authenticatedusersrole: false
   id: 778fa3d0-a2ef-4d2b-98b8-e6c7d8ce1444
   name: Administrators
   ```

2. Parse each file and compile a list of existing web roles (name, id, and flags).

3. Present the existing roles to the user:

   > "I found the following existing web roles in your site:"
   > - **Administrators** (id: `778fa3d0-...`, authenticated: false, anonymous: false)
   > - *(etc.)*

4. If no roles exist yet, inform the user:

   > "No web roles are currently defined for your site."

**Output**: Complete list of existing web roles with their names, IDs, and flags

---

## Phase 3: Determine New Roles

**Goal**: Decide which new web roles to create based on site needs and user input

**Actions**:

<!-- gate: create-webroles:3.role-selection | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · create-webroles:3.role-selection):** Multi-select over suggested + custom web roles. Drives the Phase 4 YAML file writes.
>
> **Trigger:** Phase 2 inventoried existing roles; Phase 3 suggests new ones.
> **Why we ask:** Wrong roles get created locally — fixable but adds churn to the `.powerpages-site/web-roles/` folder.
> **Cancel leaves:**