API Evangelist conversational phrasing for Forge Roles API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Forge Roles API
  version: 1.0.0
extends: openapi/laravel-roles-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/predefined-roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List Forge's predefined roles
      effect: read
      questions:
      - What built-in roles are available out of the box?
      - Which predefined roles include a given permission?
      instructions:
      - text: List the predefined roles.
      - text: Show predefined roles that include permission {permission}.
        slots:
          permission: query.filter[permissions.name]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/predefined-roles/{role}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a predefined role
      effect: read
      questions:
      - What permissions does a specific built-in role grant?
      - Can I inspect one predefined role before assigning it?
      instructions:
      - text: Show predefined role {role}.
        slots:
          role: path.role
      - text: Get the built-in role {role} and its permissions.
        slots:
          role: path.role
      method: generated
      generated: '2026-10-01'
- target: $.paths['/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List all available permissions
      effect: read
      questions:
      - Which permissions can I assign to a role?
      - Can I search the permission catalog by name?
      instructions:
      - text: List all permissions.
      - text: Find permissions named {name}.
        slots:
          name: query.filter[name]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/permissions/{permission}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a permission
      effect: read
      questions:
      - What does a specific permission allow?
      - Where can I look up a single permission's details?
      instructions:
      - text: Show permission {permission}.
        slots:
          permission: path.permission
      - text: Describe what permission {permission} grants.
        slots:
          permission: path.permission
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List my organization's custom roles
      effect: read
      questions:
      - What roles has my organization defined?
      - Which of our custom roles carry a certain permission?
      instructions:
      - text: List roles in organization {organization}.
        slots:
          organization: path.organization
      - text: Show our roles in {organization} that have permission {permission}.
        slots:
          organization: path.organization
          permission: query.filter[permissions.name]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom role
      effect: write
      questions:
      - How do I create a custom role for my organization?
      - Can I set a role's permissions at the moment I create it?
      instructions:
      - text: Create role {name} in organization {organization}.
        slots:
          name: requestBody.name
          organization: path.organization
      - text: Add role {name} to {organization} with permissions {permissions}.
        slots:
          name: requestBody.name
          organization: path.organization
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles/{role}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my organization's roles
      effect: read
      questions:
      - What are the details of a custom role in my organization?
      - Which permissions and description does one specific role of ours have?
      instructions:
      - text: Show role {role} in organization {organization}.
        slots:
          role: path.role
          organization: path.organization
      - text: Get our custom role {role}.
        slots:
          role: path.role
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles/{role}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a custom role
      effect: write
      questions:
      - How do I change the permissions on an existing role?
      - Can I rename a role and add a description?
      instructions:
      - text: 'Update role {role} in {organization}: name {name}, permissions {permissions}.'
        slots:
          role: path.role
          organization: path.organization
          name: requestBody.name
          permissions: requestBody.permissions
      - text: Rename our role {role} to {name} with description {description}.
        slots:
          role: path.role
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles/{role}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom role
      effect: destructive
      questions:
      - How do I remove a role we no longer use?
      - Can I delete a custom role from my organization?
      instructions:
      - text: Delete role {role} from organization {organization}.
        slots:
          role: path.role
          organization: path.organization
      - text: Remove our custom role {role}.
        slots:
          role: path.role
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/roles/{role}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the permissions on a role
      effect: read
      questions:
      - Which permissions does one of our roles have?
      - Does a particular role include a permission I'm looking for?
      instructions:
      - text: List permissions on role {role} in {organization}.
        slots:
          role: path.role
          organization: path.organization
      - text: Check whether role {role} has permission {name}.
        slots:
          role: path.role
          name: query.filter[name]
      method: generated
      generated: '2026-10-01'