Use read-only search_paths for Business Applications discovery

plugins/workiq-preview/skills/workiq-preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workiq-preview
-description: WorkIQ tools for Microsoft 365 workplace data and actions. Use for email, meetings, calendar, files, SharePoint, OneDrive, Teams, people, Planner, and connected work context. Triggers include gather requirements, summarize workplace discussions, manage meetings, create an upload session, send or draft replies, manage tasks, and discover paths or schemas. Retrieve context first with explicit Grounding when available and synthesize locally; use ask only for intentional delegation to Copilot or a known/discovered agent. Exact entities, structured workflows, writes, and downloads stay on entity tools. This skill contains instructions for the WorkIQ MCP tools and must be used beforehand to understand their usage.
+description: WorkIQ tools for Microsoft 365 workplace data and actions. Use for email, meetings, calendar, files, SharePoint, OneDrive, Teams, people, Planner, and connected work context. Triggers include gather requirements, summarize workplace discussions, manage meetings, create an upload session, send or draft replies, manage tasks, and discover paths or schemas. Retrieve context first with explicit Grounding when available and synthesize locally; use ask only for intentional delegation to Copilot or a known/discovered agent. Exact entities, structured workflows, writes, and downloads stay on entity tools. This skill contains instructions for the WorkIQ MCP tools and must be used beforehand to understand their usage. Use this skill also for Microsoft Business Applications requests involving CRM, ERP, Power Apps, or Dataverse records and workflows, including requests that reference paths under /businessapps/.
 compatibility: >
   Uses the hosted WorkIQ MCP endpoint. No local package is required for MCP
   tool calls.
@@ -32,6 +32,7 @@ before calling. Never guess aliases or derive prefixes from a skill folder.
 | Call an OData function (delta, reminderView, named-file search) | `call_function` |
 | Download file or attachment bytes | `fetch_blob` |
 | Discover entity paths / inspect operation fields and body shape | `search_paths` / `get_schema` |
+| Discover or use structured records and workflows in CRM, ERP, or Power Apps | `search_paths` for unknown paths; then the exact entity or action tool — read [Business Applications](references/business-applications.md) first |
 
 Semantic does not automatically mean `retrieve` or `ask`: exact entity URLs,
 bounded listings, and known workflows stay on entity tools, with local synthesis.
@@ -95,6 +96,7 @@ for exact IDs, attribution, and same-agent `conversationId` continuation.
 | People | `/me`, `/users/{id}`, `/me/manager`, `/me/contacts` | profile, org chart, personal contacts; directory and contact IDs are not interchangeable |
 | Files | `/me/drive`, `/drives/{id}`, `/sites/{id}` | metadata via entity tools; bytes via `fetch_blob`; named OneDrive search via `call_function` |
 | Planner | `/me/planner/plans`, `/planner/tasks` | list/create/update/complete/delete |
+| Business Applications | `/businessapps/environments/` and discovered `/businessapps/...` paths | direct `fetch` for environment inventory; `search_paths` for unknown records, apps, skills, APIs, and operations |
 | Change tracking | `/me/mailFolders/inbox/messages/delta`, `/me/calendarView/delta`, `/me/contacts/delta` | `call_function` only, never `fetch` |
 
 ## Required Workflow Order
@@ -161,6 +163,7 @@ inline wording or a new message for a requested persisted reply.
 | Copy/move/rename/delete files; upload sessions | [Files](references/files-work-iq.md) |
 | Cancel/delete/reschedule/forward meetings; reminders/free-busy | [Calendar](references/calendar-work-iq.md) |
 | Mail / Teams / Planner | [Mail](references/mail-work-iq.md) / [Teams](references/teams-work-iq.md) / [Tasks](references/tasks-work-iq.md) |
+| CRM, ERP, Power Apps, Dataverse records and workflows | [Business Applications](references/business-applications.md) |
 | Reads, paging / binary downloads / delta and functions | [fetch](references/fetch-work-iq.md) / [fetch_blob](references/fetch-blob-work-iq.md) / [call_function](references/call-function-work-iq.md) |
 | Paths / schemas | [search_paths](references/search-paths-work-iq.md) / [get_schema](references/get-schema-work-iq.md) |
 | Create / update / delete / actions | [create_entity](references/create-entity-work-iq.md) / [update_entity](references/update-entity-work-iq.md) / [delete_entity](references/delete-entity-work-iq.md) / [do_action](references/do-action-work-iq.md) |

plugins/workiq-preview/skills/workiq-preview/references/business-applications.md

@@ -0,0 +1,92 @@
+# Business Applications
+
+Use WorkIQ entity tools with paths under `/businessapps/` for structured CRM,
+ERP, Power Apps, and Dataverse environments, records, apps, skills, APIs, and
+operations. This resource family is distinct from Microsoft Graph application
+registrations. Do not substitute another MCP server or invent REST paths.
+
+## Discovery and known inventory
+
+1. For an unknown record, workflow, app, skill, API, operation, or identifier,
+   call `search_paths` once with a focused natural-language description. Use the
+   fields accepted by the connected WorkIQ schema. Treat discovery as grounded
+   only when the response contains a `/businessapps/...` path.
+2. For environment inventory, skip discovery and call `fetch` directly on
+   `/businessapps/environments/`. Use the exact returned environment IDs; never
+   assume a default environment.
+3. If discovery errors or returns no `/businessapps/...` path, do not repeat or
+   broaden it. Use the environment inventory, select only the exact requested
+   environment, and inspect only its relevant returned collection. Abstain when
+   the exact environment or capability is absent.
+4. Follow exact returned paths with `fetch`, `get_schema`, or the effect-correct
+   write/action tool. Do not guess path segments, IDs, names, or casing.
+5. Before an unfamiliar write or action, call `get_schema` on the concrete
+   path with the matching operation type. Schema availability does not grant
+   authorization.
+
+Discovery is read-only: use `search_paths`, not `do_action` on
+`/businessapps/me`. `do_action` remains appropriate for a discovered
+environment SQL query, Custom API, app operation, or in-app MCP tool.
+
+Do not use `do_action` on `/businessapps/me` for discovery even if that route is
+exposed; use `search_paths` instead. The old route is POST-shaped and can be
+policy-denied before any grounded path is returned, ending the workflow before
+`search_paths` or `fetch` can run.
+
+## Exact tool and path selection
+
+| Intent | Tool and path |
+| --- | --- |
+| List environments or identify the default | `fetch` `/businessapps/environments/` |
+| List or inspect tables | `fetch` or `get_schema` on `/businessapps/environments/{environmentId}/tables[/<tableName>]` |
+| Read a record | `fetch` `/businessapps/environments/{environmentId}/tables/{tableName}/records/{recordId}` |
+| Query environment data | `do_action` `/businessapps/environments/{environmentId}/query` with schema-defined `jsonBody`, including read-only `querytext` when required |
+| Create a record | `create_entity` on `/businessapps/environments/{environmentId}/tables/{tableName}/records` |
+| Update or delete a record | `update_entity` or `delete_entity` on the exact discovered record path |
+| List or inspect apps | `fetch` `/businessapps/environments/{environmentId}/apps[/<appName>]` |
+| List or inspect business skills | `fetch` `/businessapps/environments/{environmentId}/skills[/{skillName}]` |
+| Run an app operation | `do_action` on the exact discovered `.../operations/{operationName}` path |
+| Invoke a Custom API | `do_action` on the exact discovered `/businessapps/environments/{environmentId}/customapis/{apiName}` path |
+
+Environment SQL and Custom APIs with request bodies are actions, not OData
+functions. Use `call_function` only for a function path returned by discovery.
+Business Applications file routes are also distinct from Graph `fetch_blob` and
+the unreleased Graph `upload_blob`; use only the operation returned by the
+Business Applications schema.
+
+## Confirmation, policy, and failure boundaries
+
+Classify effects from the discovered operation contract. Apply the general
+confirmation workflow before `create_entity`, `update_entity`, `delete_entity`,
+or a mutating `do_action`. A read-only SQL query does not require mutation
+confirmation merely because it uses `do_action`.
+
+WorkIQ may deny an action or mutation based on caller trust, tenant policy, or
+resource privileges. This does not make read-only `search_paths` discovery or a
+permitted structural `fetch` into mutations. On an explicit denial:
+
+- stop the affected workflow and report the observed diagnostic;
+- do not retry through another path, tool, agent, endpoint, or plugin;
+- do not assert that a particular tenant setting or consent change will fix it
+  unless the diagnostic says so; and
+- do not claim success or substitute a different record, table, skill, or app.
+
+A named but unavailable environment is a hard stop. An approved create or
+update requires a matching write receipt and, when supported, read-back of that
+exact target; a pre-existing lookalike is not proof of completion. Never use a
+saved view or ordinary record update as a schema-customization fallback.
+
+When the outcome of a mutation is ambiguous, do not replay it. Reconcile with a
+supported safe read when available; otherwise report **outcome unknown**.
+
+## Grounding and capability matching
+
+- Preserve exact returned IDs and paths. Structural segments can be
+  case-insensitive, but opaque identifiers are not.
+- For metadata with an unknown path, use `search_paths`, then fetch the returned
+  resource. For known structural inventory, use the direct `fetch` path.
+- A top-level semantic retrieval may include Dataverse evidence, but it does not
+  replace authoritative path discovery for a requested Business Applications
+  record or operation.
+- A named skill, app operation, or Custom API requires an exact discovered
+  capability match. Do not silently substitute a similar capability.

plugins/workiq-preview/skills/workiq-preview/references/do-action-work-iq.md

@@ -2,8 +2,9 @@
 
 Invoke a named WorkIQ action. An action can read, mutate, or create a resource;
 POST and the tool name alone do not establish its effects. Read-only free/busy,
-structured search, and Business Applications discovery do not require mutation
-confirmation just because they use this tool.
+and structured search do not require mutation confirmation just because they
+use this tool. Use `search_paths`, not `do_action`, for Business Applications
+discovery.
 
 ## Parameters
 
@@ -42,6 +43,7 @@ mutations even if they do not send a message.
 | Accept/decline, cancellation, forwarding, free/busy | [Calendar](calendar-work-iq.md) |
 | Drive-scoped copy and upload-session creation | [Files](files-work-iq.md) |
 | Read/unread, reactions, presence | [Teams](teams-work-iq.md) |
+| Environment SQL, Custom APIs, and app operations | [Business Applications](business-applications.md) |
 
 Use [create_entity](create-entity-work-iq.md) for collection creation such as a
 fresh draft; `createReply`/`createReplyAll`/`createForward` remain actions.

plugins/workiq-preview/skills/workiq-preview/references/search-paths-work-iq.md

@@ -6,15 +6,14 @@ preflight. This tool does not discover MCP tool names; use the connected catalog
 
 ## Live argument contract
 
-The connected catalog inspected for this guidance exposes required `query`
-(string): a natural-language resource/action description or a path prefix.
-Older catalogs may expose a regex `filter` instead. Inspect the actual advertised
-schema and send only its accepted fields; do not translate examples into guessed
-arguments or try both interfaces after rejection.
+The connected WorkIQ catalog exposes natural-language and structural discovery.
+Inspect its advertised schema and send only accepted fields; do not translate
+examples into guessed arguments or try another interface after rejection.
 
-There is no basis for inventing `backend`, `source`, or `provider` selectors.
-Nor does path discovery imply that the entire catalog is Graph-only: retain
-exact returned resource families and their domain contracts.
+There is no `backend`, `source`, or `provider` argument. WorkIQ may fan out to
+enabled providers, but only returned paths prove participation. Require a
+returned `/businessapps/...` path before following a Business Applications
+result.
 
 ## Workflow
 
@@ -29,11 +28,21 @@ Use [recovery](troubleshooting.md) for failures. Explicit denial stops; no route
 agent, or tool substitution. An empty result means no matching path was confirmed
 in that search, not that the entire service lacks the capability.
 
+If Business Applications discovery errors or returns no `/businessapps/...`
+path, do not repeat or broaden it. Fetch `/businessapps/environments/`, resolve
+only the exact requested environment, and inspect only its relevant returned
+collection. Abstain when the exact environment or capability is absent.
+
 When asked for all available matching paths, summarize every returned family and
 operation, not just common examples. Inspect an available saved capped result
 before claiming coverage; if the response is truncated, qualify completeness.
 Do not invent paths absent from the result.
 
+For structured CRM, ERP, Power Apps, or Dataverse resources and workflows, read
+[Business Applications](business-applications.md). Use natural-language
+`search_paths` for unknown paths, but use direct
+`fetch("/businessapps/environments/")` for environment inventory.
+
 ## Examples for the `query` catalog
 
 ```json

plugins/workiq-preview/skills/workiq-preview/references/troubleshooting.md

@@ -6,8 +6,8 @@ may impose tighter bounds; a happy-path call budget never overrides safety.
 ## Classify effects before recovery
 
 Classify the operation by its documented effects, not the tool name or HTTP verb.
-`do_action` can perform read-only `getSchedule`, `/search/query`, or Business
-Applications discovery. Persisting a draft, changing read state or presence,
+`do_action` can perform read-only `getSchedule` or `/search/query` operations.
+Persisting a draft, changing read state or presence,
 creating an upload session, and sending, updating, or deleting are mutations.
 If effects are unknown, inspect the live contract before execution.
 
@@ -78,8 +78,10 @@ Use WorkIQ server-relative paths without scheme, authority, or API version.
 Encode query values and preserve opaque IDs; do not guess missing identifiers.
 Only attribute a `400` to formatting when the diagnostic demonstrates it.
 See [path discovery](search-paths-work-iq.md) and [schemas](get-schema-work-iq.md).
-Do not invent `backend`, `provider`, or response-schema selectors. Schema presence
-does not grant runtime permission or prove a request was accepted.
+For `search_paths`, inspect the live schema and send only its accepted `query`
+or legacy `filter` input; never try both interfaces after rejection. Do not
+invent `backend`, `provider`, or response-schema selectors. Schema presence does
+not grant runtime permission or prove a request was accepted.
 
 ## `fetch_blob` or `upload_blob` unavailable