API Evangelist conversational phrasing for TextQL App Service API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for TextQL App Service API
  version: 1.0.0
extends: openapi/textql-appservice-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: 24
- target: $.paths['/textql.rpc.public.app.AppService/AppHeartbeat'].post
  update:
    x-apievangelist-phrasing:
      intent: Keep a viewed app's compute worker alive
      effect: write
      questions:
      - How do I keep a data app's compute worker warm while someone is viewing it?
      - Does an app's worker shut down if no heartbeat is sent?
      instructions:
      - text: Send a keep-alive heartbeat for app {appId}.
        slots:
          appId: requestBody.appId
      - text: Keep the compute worker for {appId} running.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/CreateApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new data app
      effect: write
      questions:
      - How do I build a new data app in TextQL from code and data sources?
      - Can a new app include compute functions and its own app database setup?
      instructions:
      - text: Create an app named {name} with code {code}.
        slots:
          name: requestBody.name
          code: requestBody.code
      - text: Make a new app {name} described as {description} using data sources {dataSources}.
        slots:
          name: requestBody.name
          description: requestBody.description
          dataSources: requestBody.dataSources
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/DeleteApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a data app
      effect: destructive
      questions:
      - How do I permanently remove an app I no longer need?
      - Can I delete a data app someone else created?
      instructions:
      - text: Delete app {appId}.
        slots:
          appId: requestBody.appId
      - text: Remove the data app with id {appId} from the library.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/DuplicateApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate an app into a copy I own
      effect: write
      questions:
      - Can I make my own copy of an app someone shared with me?
      - Does duplicating an app copy its data snapshot too?
      instructions:
      - text: Duplicate app {appId} into a copy I own.
        slots:
          appId: requestBody.appId
      - text: Make a Copy of app {appId} with its code, files and schedule.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a data app's details
      effect: read
      questions:
      - How do I look up the code and settings of a specific app?
      - What data sources and compute functions does an app declare?
      instructions:
      - text: Get app {appId}.
        slots:
          appId: requestBody.appId
      - text: Show the definition and settings of data app {appId}.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetAppDBSchema'].post
  update:
    x-apievangelist-phrasing:
      intent: Get the schema of an app's database
      effect: read
      questions:
      - Which tables and columns does my app's built-in database have?
      - Can I inspect an app database schema before querying it?
      instructions:
      - text: Show the app database schema for {appId}.
        slots:
          appId: requestBody.appId
      - text: Describe the tables in the database behind app {appId}.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetAppDBTablePreview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview rows in an app database table
      effect: read
      questions:
      - Can I peek at the first rows of a table in my app's database?
      - How many rows can an app table preview return?
      instructions:
      - text: Preview table {tableName} in app {appId}.
        slots:
          tableName: requestBody.tableName
          appId: requestBody.appId
      - text: Show the first {limit} rows of {tableName} from app {appId}'s database.
        slots:
          limit: requestBody.limit
          tableName: requestBody.tableName
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetAppMemberState'].post
  update:
    x-apievangelist-phrasing:
      intent: Read my saved per-member state for an app
      effect: read
      questions:
      - Does an app remember my own settings, and how do I read them back?
      - Where is my per-user state for a data app stored?
      instructions:
      - text: Get my member state for app {appId}.
        slots:
          appId: requestBody.appId
      - text: Load the values app {appId} saved for me.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetAppVersion'].post
  update:
    x-apievangelist-phrasing:
      intent: Get one saved version of an app
      effect: read
      questions:
      - Can I look at what an app looked like at an earlier version?
      - How do I fetch a past app version by number or commit?
      instructions:
      - text: Get version {versionNumber} of app {appId}.
        slots:
          versionNumber: requestBody.versionNumber
          appId: requestBody.appId
      - text: Show app {appId} as of commit {commitId}.
        slots:
          appId: requestBody.appId
          commitId: requestBody.commitId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetAppViewStats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get view analytics for an app
      effect: read
      questions:
      - How many people have viewed my data app?
      - Is there engagement data for when an app page was loaded?
      instructions:
      - text: Show view stats for app {appId}.
        slots:
          appId: requestBody.appId
      - text: Report how often app {appId} has been opened.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/GetMembersWithApps'].post
  update:
    x-apievangelist-phrasing:
      intent: List members who have created apps
      effect: read
      questions:
      - Which people in my organization have built apps?
      - Can I see app authors so I can filter the library by creator?
      instructions:
      - text: List members who own apps.
      - text: Show app authors in my org, timing out after {timeout_ms} ms.
        slots:
          timeout_ms: header.Connect-Timeout-Ms
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/InvokeAppComputeFunction'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an app's compute function
      effect: write
      questions:
      - How do I call a compute function an app declared?
      - Are app compute function calls rate-limited?
      instructions:
      - text: Invoke compute function {functionName} on app {appId}.
        slots:
          functionName: requestBody.functionName
          appId: requestBody.appId
      - text: Run {functionName} in app {appId} with parameters {paramsJson}.
        slots:
          functionName: requestBody.functionName
          appId: requestBody.appId
          paramsJson: requestBody.paramsJson
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/ListAppActivitySince'].post
  update:
    x-apievangelist-phrasing:
      intent: List app activity after a sequence point
      effect: read
      questions:
      - What activity has happened in an app since I last checked?
      - Can I poll an app's activity feed from a known sequence number?
      instructions:
      - text: List activity on app {appId} after sequence {afterSeq}.
        slots:
          appId: requestBody.appId
          afterSeq: requestBody.afterSeq
      - text: Fetch up to {limit} new activity events in scope {scope} for app {appId}.
        slots:
          limit: requestBody.limit
          scope: requestBody.scope
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/ListAppVersions'].post
  update:
    x-apievangelist-phrasing:
      intent: List an app's version history
      effect: read
      questions:
      - How many saved versions does my app have?
      - Can I page through an app's version history?
      instructions:
      - text: List versions of app {appId}.
        slots:
          appId: requestBody.appId
      - text: Show {limit} versions of app {appId} starting at offset {offset}.
        slots:
          limit: requestBody.limit
          appId: requestBody.appId
          offset: requestBody.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/ListApps'].post
  update:
    x-apievangelist-phrasing:
      intent: List and search data apps
      effect: read
      questions:
      - Which apps are in my TextQL library?
      - Can I search apps by name or only see the ones shared with me?
      - How do I list apps that are not in any folder?
      instructions:
      - text: Search apps for {searchTerm}.
        slots:
          searchTerm: requestBody.searchTerm
      - text: List the apps in folder {folderId}.
        slots:
          folderId: requestBody.folderId
      - text: Show apps shared with me.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/ListMyAppMemberActivity'].post
  update:
    x-apievangelist-phrasing:
      intent: List my own activity in an app
      effect: read
      questions:
      - What actions have I taken inside a particular app?
      - Can I filter my app activity by type?
      instructions:
      - text: List my activity in app {appId}.
        slots:
          appId: requestBody.appId
      - text: Show my last {limit} {type} events in app {appId}.
        slots:
          limit: requestBody.limit
          type: requestBody.type
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/MoveAppToFolder'].post
  update:
    x-apievangelist-phrasing:
      intent: Move an app into a library folder
      effect: write
      questions:
      - How do I organize an app into a folder in the library?
      - Can I move an app back to the library root?
      instructions:
      - text: Move app {appId} into folder {folderId}.
        slots:
          appId: requestBody.appId
          folderId: requestBody.folderId
      - text: Move app {appId} to the library root.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/PresenceHeartbeat'].post
  update:
    x-apievangelist-phrasing:
      intent: Report that I'm present in an app
      effect: write
      questions:
      - How does an app show who else is looking at it right now?
      - Can I report presence in a specific zone of an app?
      instructions:
      - text: Send a presence heartbeat for app {appId}.
        slots:
          appId: requestBody.appId
      - text: Mark me present in zone {zone} of app {appId}.
        slots:
          zone: requestBody.zone
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/RecordAppMemberActivity'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an activity event in an app
      effect: write
      questions:
      - How do I log a user action from inside a data app?
      - Can I avoid recording the same app activity twice with an idempotency key?
      instructions:
      - text: Record a {type} activity in app {appId} with payload {payloadJson}.
        slots:
          type: requestBody.type
          appId: requestBody.appId
          payloadJson: requestBody.payloadJson
      - text: Log activity on app {appId} using idempotency key {idemKey}.
        slots:
          appId: requestBody.appId
          idemKey: requestBody.idemKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/RefreshApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh an app's data snapshot
      effect: write
      questions:
      - How do I make an app re-fetch its data sources?
      - Can I rebuild an app with a fresh data snapshot on demand?
      instructions:
      - text: Refresh app {appId}.
        slots:
          appId: requestBody.appId
      - text: Re-pull the data behind app {appId} and rebuild it.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/RestoreAppVersion'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an app to an earlier version
      effect: write
      questions:
      - Can I roll my app back to a previous version?
      - How do I undo a bad save by restoring an older app version?
      instructions:
      - text: Restore app {appId} to version {versionNumber}.
        slots:
          appId: requestBody.appId
          versionNumber: requestBody.versionNumber
      - text: Roll app {appId} back to commit {commitId}.
        slots:
          appId: requestBody.appId
          commitId: requestBody.commitId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/SetAppMemberState'].post
  update:
    x-apievangelist-phrasing:
      intent: Save my per-member state for an app
      effect: write
      questions:
      - How does an app persist settings for just me?
      - Can I store a JSON value as my personal state in an app?
      instructions:
      - text: Save my state {valueJson} for app {appId}.
        slots:
          valueJson: requestBody.valueJson
          appId: requestBody.appId
      - text: Overwrite my stored member state in app {appId}.
        slots:
          appId: requestBody.appId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/SetFavorite'].post
  update:
    x-apievangelist-phrasing:
      intent: Favorite or unfavorite an app or dashboard
      effect: write
      questions:
      - How do I pin an app or dashboard to my favorites?
      - Can I remove a library item from my favorites?
      instructions:
      - text: Favorite {primitiveType} {primitiveId}.
        slots:
          primitiveType: requestBody.primitiveType
          primitiveId: requestBody.primitiveId
      - text: Set favorited to {favorited} on library item {primitiveId}.
        slots:
          favorited: requestBody.favorited
          primitiveId: requestBody.primitiveId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/textql.rpc.public.app.AppService/UpdateApp'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a data app
      effect: write
      questions:
      - How do I change an existing app's code or description?
      - Can I put an app on a cron schedule so its data refreshes automatically?
      - Does updating an app replace its data sources or add to them?
      instructions:
      - text: Update app {appId} with new code {code}.
        slots:
          appId: requestBody.appId
          code: requestBody.code
      - text: Schedule app {appId} to refresh on cron {cronString}.
        slots:
          appId: requestBody.appId
          cronString: requestBody.cronString
      - text: Rename app {appId} to {name} and publish it.
        slots:
          appId: requestBody.appId
          name: requestBody.name
      method: generated
      generated: '2026-10-01'