API Evangelist conversational phrasing for Chef Automate API Documentation Policies API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Chef Automate API Documentation Policies API
  version: 1.0.0
extends: openapi/progress-software-policies-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['/apis/iam/v2/policies'].get
  update:
    x-apievangelist-phrasing:
      intent: List IAM policies
      effect: read
      questions:
      - Which IAM policies exist in my Chef Automate install?
      - Can I see both custom and Chef-managed access policies in one list?
      instructions:
      - text: List all IAM policies.
      - text: Show every access policy defined in Automate.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom IAM policy
      effect: write
      questions:
      - How do I create a policy that grants a team a role on specific projects?
      - Can a new policy's statement be scoped to every project at once?
      instructions:
      - text: Create policy {id} named {name} with statements {statements}.
        slots:
          id: requestBody.id
          name: requestBody.name
          statements: requestBody.statements
      - text: Create custom policy {id} called {name} granting {statements} to members {members}.
        slots:
          id: requestBody.id
          name: requestBody.name
          statements: requestBody.statements
          members: requestBody.members
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one IAM policy
      effect: read
      questions:
      - What statements and members are on a specific policy?
      - Can I look up a single access policy by its ID?
      instructions:
      - text: Get IAM policy {id}.
        slots:
          id: path.id
      - text: Show the statements, members and projects of policy {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Overwrite a custom IAM policy
      effect: write
      questions:
      - How do I change the statements on an existing custom policy?
      - Does updating a policy reset any fields I leave out of the request?
      instructions:
      - text: Overwrite policy {id} with name {name} and statements {statements}.
        slots:
          id: path.id
          name: requestBody.name
          statements: requestBody.statements
      - text: Replace the full definition of policy {id}, setting name {name}, statements {statements} and projects {projects}.
        slots:
          id: path.id
          name: requestBody.name
          statements: requestBody.statements
          projects: requestBody.projects
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom IAM policy
      effect: destructive
      questions:
      - How do I delete a custom access policy?
      - Can Chef-managed policies be deleted, or only custom ones?
      instructions:
      - text: Delete custom policy {id}.
        slots:
          id: path.id
      - text: Remove IAM policy {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}/members'].get
  update:
    x-apievangelist-phrasing:
      intent: List the members of a policy
      effect: read
      questions:
      - Which users, teams and tokens are members of a given policy?
      - Who is granted access through a particular policy?
      instructions:
      - text: List the members of policy {id}.
        slots:
          id: path.id
      - text: Show who belongs to policy {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}/members'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a policy's entire member list
      effect: write
      questions:
      - How do I swap out the whole member list of a policy in one call?
      - What format do member expressions need when I replace a policy's members?
      instructions:
      - text: Replace all members of policy {id} with {members}.
        slots:
          id: path.id
          members: requestBody.members
      - text: Set the member list of policy {id} to exactly {members}, dropping anyone else.
        slots:
          id: path.id
          members: requestBody.members
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}/members:add'].post
  update:
    x-apievangelist-phrasing:
      intent: Add members to a policy
      effect: write
      questions:
      - How do I grant a new team access by adding it to an existing policy?
      - Can I add members to a Chef-managed policy like Administrator?
      instructions:
      - text: Add members {members} to policy {id}.
        slots:
          members: requestBody.members
          id: path.id
      - text: Grant policy {id} to the additional members {members}, keeping current ones.
        slots:
          id: path.id
          members: requestBody.members
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policies/{id}/members:remove'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove members from a policy
      effect: write
      questions:
      - How do I revoke a user's access granted through a specific policy?
      - What happens if I remove a member who isn't on the policy?
      instructions:
      - text: Remove members {members} from policy {id}.
        slots:
          members: requestBody.members
          id: path.id
      - text: Take {members} off the member list of policy {id}.
        slots:
          members: requestBody.members
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/apis/iam/v2/policy_version'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the IAM version Automate is running
      effect: read
      questions:
      - Which IAM version is my Automate installation running?
      - Is my Automate on IAM v2?
      instructions:
      - text: Get the IAM major and minor version.
      - text: Tell me which IAM version this Automate install uses.
      method: generated
      generated: '2026-10-01'