docs: make WorkIQ guidance grounding-first and host-neutral

.claude-plugin/marketplace.json

@@ -7,14 +7,14 @@
   "plugins": [
     {
       "name": "workiq",
-      "description": "Full WorkIQ tool surface \u2014 agentic queries via ask plus direct reads and writes (create, update, delete, send) across emails, meetings, calendar, Planner tasks, documents, Teams, people and contacts, OneDrive, and SharePoint.",
-      "version": "2.0.2",
+      "description": "WorkIQ for Microsoft 365 email, calendars, meetings, Teams messages, SharePoint and OneDrive files, people and contacts, Planner tasks, and Business Applications. Search, summarize, read, create, update, delete, send, and download using supported tools, with confirmation for mutations. Use retrieve-first context with explicit Grounding when available, intentional Copilot or named-agent delegation via ask, and entity tools for exact operations.",
+      "version": "2.1.0",
       "source": "./plugins/workiq"
     },
     {
       "name": "workiq-preview",
-      "description": "Preview build: full WorkIQ tool surface \u2014 agentic queries via ask plus direct reads and writes (create, update, delete, send) across emails, meetings, calendar, Planner tasks, documents, Teams, people and contacts, OneDrive, and SharePoint.",
-      "version": "0.5.1",
+      "description": "Preview WorkIQ for Microsoft 365 email, calendars, meetings, Teams messages, SharePoint and OneDrive files, people and contacts, and Planner tasks. Search, summarize, read, create, update, delete, send, and download using supported tools, with confirmation for mutations. Use retrieve-first context with explicit Grounding when available, intentional Copilot or named-agent delegation via ask, and entity tools for exact operations.",
+      "version": "2.1.0",
       "source": "./plugins/workiq-preview"
     },
     {

.github/workflows/workiq-guidance.yml

@@ -0,0 +1,47 @@
+name: WorkIQ guidance contracts
+
+on:
+  pull_request:
+    paths:
+      - 'plugins/workiq/**'
+      - 'plugins/workiq-preview/**'
+      - '*.md'
+      - 'marketplace.json'
+      - '.claude-plugin/marketplace.json'
+      - 'tests/workiq-guidance/**'
+      - '.github/workflows/workiq-guidance.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/workiq/**'
+      - 'plugins/workiq-preview/**'
+      - '*.md'
+      - 'marketplace.json'
+      - '.claude-plugin/marketplace.json'
+      - 'tests/workiq-guidance/**'
+      - '.github/workflows/workiq-guidance.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  contracts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '22'
+      - name: Install test-only parsers
+        run: npm ci --ignore-scripts --no-audit --no-fund
+        working-directory: tests/workiq-guidance
+      - name: Trace-oracle unit tests (not observed agent behavior)
+        run: npm run test:oracle
+        working-directory: tests/workiq-guidance
+      - name: Static documentation and contract checks
+        run: npm run test:static
+        working-directory: tests/workiq-guidance

AGENTS.md

@@ -1,19 +1,24 @@
 # Work IQ
 
-Work IQ is a **Copilot CLI plugin marketplace** for managing AI agent plugins for GitHub Copilot CLI. It provides MCP servers, skills, and tools that connect AI assistants to Microsoft 365 data.
+Work IQ is an **agent-host-neutral plugin collection**. Its MCP servers, skills,
+and tools connect compatible AI agents to Microsoft 365 data; it is not specific
+to GitHub Copilot CLI. This repository includes plugin metadata for GitHub Copilot,
+Claude, and Codex. Shared routing and safety policy applies in every host; packaging,
+authentication, tool discovery, and skill loading follow each host's capabilities.
 
 ## Repository Structure
 
 ```
 work-iq/
-├── .github/
-│   └── plugin/
-│       └── marketplace.json  # Plugin marketplace registry
+├── .github/workflows/       # Automation and guidance contract checks
+├── marketplace.json        # Copilot plugin marketplace registry
+├── .claude-plugin/marketplace.json # Mirrored Claude marketplace registry
 ├── plugins/                  # Plugin packages (skills + MCP servers)
 │   ├── workiq/
 │   ├── workiq-preview/
 │   ├── microsoft-365-agents-toolkit/
 │   └── workiq-productivity/
+├── tests/workiq-guidance/    # Synthetic contracts, documentation checks, trace oracle
 ├── server.json               # MCP server manifest
 ├── ADMIN-INSTRUCTIONS.md     # Tenant admin consent guide
 ├── CONTRIBUTING.md           # Guide for adding new plugins
@@ -23,9 +28,17 @@ work-iq/
 
 ## Installing Plugins
 
-This repo is a [Copilot CLI plugin marketplace](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace). Install plugins using the marketplace workflow below.
+Use the selected agent host's plugin installer and reload mechanism. Each package
+contains `.github/plugin/plugin.json`, `.claude-plugin/plugin.json`, and
+`.codex-plugin/plugin.json`; root marketplace manifests serve the corresponding
+hosts. These are distribution adapters, not different Work IQ policies.
+See [installation by host](PLUGINS.md#installation-by-host).
 
-### Quick install (copy-paste ready)
+### GitHub Copilot CLI example
+
+The following commands are specific to
+[Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-marketplace),
+not prerequisites for other agents:
 
 ```bash
 copilot plugin install ./plugins/workiq
@@ -34,15 +47,16 @@ copilot plugin install ./plugins/microsoft-365-agents-toolkit
 copilot plugin install ./plugins/workiq-productivity
 ```
 
-> **Important:** After installing, restart your Copilot CLI session for new skills to become available.
+> **Important:** Reload skills or restart the selected host after installation.
+> An MCP-only connection does not automatically load the bundled skill policy.
 
-### Check what's installed
+### Check what's installed in Copilot CLI
 
 ```bash
 copilot plugin list
 ```
 
-### Removing a plugin
+### Removing a plugin in Copilot CLI
 
 ```bash
 copilot plugin uninstall workiq
@@ -68,12 +82,54 @@ plugins/<plugin-name>/
 ### Available plugins
 
 - **workiq** — Full WorkIQ tool surface for Microsoft 365 (read + write). Bundles:
-  - `workiq` skill — Guides usage of `ask` for semantic questions plus the entity tools for fast, structured M365 reads and writes
-  - Hosted MCP server (`workiq`) with tools: `ask_work_iq`, `fetch_work_iq`, `fetch_blob_work_iq`, `get_schema_work_iq`, `search_paths_work_iq`, `create_entity_work_iq`, `update_entity_work_iq`, `delete_entity_work_iq`, `do_action_work_iq`, `call_function_work_iq`, `get_debug_link`
+  - `workiq` skill — Retrieve-first caller-owned context with explicit Grounding when available; intentional Copilot/known-agent delegation with `ask`; exact M365/Business Applications reads, writes, library metadata, and downloads on entity tools
+  - Hosted MCP server (`workiq`); logical tool names include `ask`, `list_agents`, `fetch`, `fetch_blob`, `get_schema`, `search_paths`, `create_entity`, `update_entity`, `delete_entity`, `do_action`, `call_function`, and tenant-dependent preview `retrieve`. Resolve exact names and schemas from the host's connected catalog.
 
 - **workiq-preview** — Preview build with the full WorkIQ tool surface (read + write). Bundles:
-  - `workiq-preview` skill — Guides usage of `ask_work_iq` for semantic questions plus the entity tools for fast, structured M365 reads and writes
-  - Hosted MCP server (`workiq-preview`) with tools: `ask_work_iq`, `fetch_work_iq`, `fetch_blob_work_iq`, `get_schema_work_iq`, `search_paths_work_iq`, `create_entity_work_iq`, `update_entity_work_iq`, `delete_entity_work_iq`, `do_action_work_iq`, `call_function_work_iq`, `get_debug_link`
+  - `workiq-preview` skill — Same retrieve/ask/entity routing, with its own bundled `references/retrieve-work-iq.md`
+  - Hosted MCP server (`workiq-preview`); discover its actual tool catalog. Installing this plugin does not enable server-side preview tools for a tenant.
+
+For both skills, explicitly send `strategy: "grounding"` for ordinary caller-owned
+context, including unspecified or unknown locations. The API's omitted-parameter
+default remains `copilot`; this skill intentionally chooses a different default.
+Use Copilot retrieval directly for required broader sources or `Dataverse`/
+`GraphConnectors`; preserve source restrictions. `ask` requires intentional
+delegation, with exact IDs from `list_agents` when a named agent is unresolved.
+No automatic retrieval-to-ask fallback, no broader retry for an empty result or
+cap alone, and at most one justified targeted broader escalation per objective.
+When source families are unspecified, omit `capabilities`; do not guess a narrower
+allow-list from the topic. Restrict only for explicit source requirements or a
+concrete justified source need while preserving all required families.
+
+Keep shared routing and safety aligned across both packages. Public-only
+SharePoint/library-metadata and Business Applications references and dispatch links
+are intentional exceptions, not permission for shared-policy drift. Each workflow
+has one canonical owner: `files-work-iq.md`, `calendar-work-iq.md`, `mail-work-iq.md`,
+`teams-work-iq.md`, or `tasks-work-iq.md`; `agents-work-iq.md` owns agent discovery.
+`workflows-work-iq.md` is the index, setup, people, and cross-domain guide.
+`troubleshooting.md` owns operation-aware recovery. Read only the relevant contract.
+`workiq` and `workiq-preview` may version independently. For each package, use
+its own entry in root `marketplace.json` as the version reference and synchronize
+its mirrored marketplace entry and GitHub/Claude/Codex manifests. Matching
+versions for a particular release do not establish a permanent lockstep policy.
+The guidance gate checks consistency within each package, not between packages.
+Plugin descriptions must lead with discoverable workloads and actions, not only
+retrieval policy. Keep email, calendar/meetings, Teams, SharePoint/OneDrive files,
+people/contacts, Planner, and supported operations explicit; retain public-only
+Business Applications coverage. Hosts may use plugin metadata, skill frontmatter,
+or tool descriptions differently, so none of these layers replaces the others.
+
+Confirmation and denial stops override happy-path call budgets. Classify effects
+by operation, not tool name: `do_action` can be read-only. Never replay ambiguous
+mutations; report accepted/pending or unknown outcomes honestly. Preserve mainline
+library-column source truth, completeness, Business Applications paths, and privilege
+boundaries. Ordinary calendar windows use `fetch`; explicit delta uses `call_function`
+and needs a checkpoint for historical change claims. Persisted reply drafts use
+`do_action` without sending; exchanged-mail reconstruction excludes unsent drafts.
+Calendar URL boundaries must use offsets for their requested dates and timezone,
+not today's offset. Resolve both boundaries independently and round-trip them
+through the named zone; use schema-defined local `dateTime`/`timeZone` pairs only
+where the action supports them. Keep these rules consistent in both packages.
 
 - **microsoft-365-agents-toolkit** — Toolkit for building M365 Copilot declarative agents. Bundles:
   - `install-atk` skill — Install or update the M365 Agents Toolkit CLI and VS Code extension
@@ -94,9 +150,31 @@ plugins/<plugin-name>/
   - `channel-audit` skill — Audit channels for inactivity and cleanup
   - `channel-digest` skill — Summarize activity across multiple channels
 
+## Guidance validation
+
+The shared synthetic contract and regression suite live in
+[`tests/workiq-guidance/`](tests/workiq-guidance/README.md). With Node 22+, run:
+
+```bash
+npm ci --prefix tests/workiq-guidance --ignore-scripts --no-audit --no-fund
+npm --prefix tests/workiq-guidance test
+```
+
+The path-filtered `workiq-guidance.yml` CI workflow runs documentation checks and
+trace-oracle tests separately. Parsed skill descriptions must stay within 1,024
+characters; local links, retrieval examples, and shared-package policy are checked.
+Static checks and synthetic oracle inputs are not observed agent behavior. Host/mock
+traces, captured endpoint schemas/responses, and matched live coverage evaluation
+remain separate evidence gates; do not claim gains or launch large live evaluations
+from an offline pass. Keep private evidence out of public fixtures.
+Record the host and adapter version for every behavioral/loading result. A Copilot
+CLI loading check is evidence for that host only, not validation of Claude, Codex,
+or another agent. Use the same logical contracts with each host's actual catalog.
+
 ## Prerequisites
 
-- **Node.js 18+** — Required for the workiq MCP server (`npx`)
+- **Compatible agent host** — Skill/plugin loading and the selected MCP connection/authentication mechanism.
+- **Node.js 18+** — Required only for the local WorkIQ CLI/stdio server (`npx`), not hosted MCP calls; guidance tests use Node 22+.
 - **Admin consent** — The WorkIQ MCP server requires tenant admin consent on first use. See the [Tenant Administrator Enablement Guide](./ADMIN-INSTRUCTIONS.md) for details.
 
 ## Creating a New Plugin
@@ -138,8 +216,8 @@ Skill instructions here...
 ```
 
 After creating a plugin:
-1. Register it in `.github/plugin/marketplace.json` by adding an entry to the `plugins` array
-2. Install it with `copilot plugin install ./plugins/my-plugin`
+1. Register it in `marketplace.json` and mirror the entry in `.claude-plugin/marketplace.json`
+2. Install it with the selected host's plugin installer; for Copilot CLI, `copilot plugin install ./plugins/my-plugin`
 
 ---
 
@@ -148,10 +226,10 @@ After creating a plugin:
 > **Important:** When making changes to this repository — adding new plugins or modifying workflows — update this AGENTS.md file to reflect those changes. This file serves as the primary context document for AI agents working in this repo. Keep it accurate and current. Specifically:
 >
 > - Add new plugins to the "Available plugins" section when they are created
-> - Register new plugins in `.github/plugin/marketplace.json`
+> - Register new plugins in `marketplace.json` and `.claude-plugin/marketplace.json`; keep host plugin descriptions aligned
 > - Update "Getting Started" if new setup steps are required
 > - Update "Repository Structure" if top-level directories change
-> - **After editing any skill or plugin content**, reinstall the affected plugin so the running session picks up the changes:
+> - **After editing any skill or plugin content**, reinstall/reload the affected plugin using the selected host's supported mechanism. Confirm the new skill/reference content is loaded in a fresh session. For Copilot CLI:
 >   ```bash
 >   copilot plugin uninstall <plugin-name>
 >   copilot plugin install ./plugins/<plugin-name>

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Thank you for your interest in contributing to the Work IQ plugin collection! This document provides guidelines for adding new plugins and improving existing ones.
 
+Work IQ is agent-host-neutral. Write skills against logical tools and live
+schemas, not one host's tool prefixes or local APIs. Keep host-specific install
+instructions and plugin manifests labeled separately from shared behavior.
+
 ## 🔌 Plugin Structure
 
 Each plugin lives in `plugins/{plugin-name}/` and follows this structure:
@@ -26,7 +30,8 @@ plugins/{plugin-name}/
 
 ### Marketplace Registry
 
-All plugins must be registered in `.github/plugin/marketplace.json`. Add your plugin entry:
+All plugins must be registered in `marketplace.json`, with a matching entry in
+`.claude-plugin/marketplace.json`. Add your plugin entry:
 
 ```json
 {
@@ -38,12 +43,17 @@ All plugins must be registered in `.github/plugin/marketplace.json`. Add your pl
 }
 ```
 
+`workiq` and `workiq-preview` may have different plugin/skill versions. For each
+package, synchronize its own root `marketplace.json` version with its mirrored
+marketplace entry and host manifests. Matching versions in one release do not
+require future releases to stay in lockstep.
+
 ## 🚀 Adding a New Plugin
 
 1. **Fork** the repository and create a feature branch
 2. **Create** your plugin directory under `plugins/`
 3. **Add** the required files (`.mcp.json`, `README.md`, `skills/*/SKILL.md`)
-4. **Register** your plugin in `.github/plugin/marketplace.json`
+4. **Register** your plugin in `marketplace.json` and `.claude-plugin/marketplace.json`
 5. **Update** the root `README.md` plugin table
 6. **Submit** a pull request
 
@@ -83,13 +93,35 @@ Description and parameters...
 - Test your MCP server starts correctly
 - Ensure your skill documentation is accurate
 
+For `workiq` or `workiq-preview` guidance changes, use Node 22+ and run:
+
+```bash
+npm ci --prefix tests/workiq-guidance --ignore-scripts --no-audit --no-fund
+npm --prefix tests/workiq-guidance test
+```
+
+Add requirement-linked synthetic cases before changing policy; keep shared
+semantics aligned and document intentional public-only reference differences.
+See the [guidance contract](tests/workiq-guidance/README.md) for parsed frontmatter,
+link, routing, parity, and trace-oracle checks. These offline layers do not prove
+agent compliance or validate deployed endpoint payloads. Captured host/mock traces
+and approved live evaluation are separate gates, with private evidence kept out
+of this repository. Do not publish benchmark-specific recipes or unverified gains.
+
+After editing plugin content, reinstall each affected plugin and restart a fresh
+host session using that host's supported mechanism. A plugin install does not
+enable tenant-gated tools. Record host/version and adapter provenance for loading
+and behavioral results; repeat the shared contract cases across the host support
+matrix. A successful Copilot CLI install does not validate Claude, Codex, or other
+agents. Unsupported/unavailable host adapters remain explicit coverage gaps.
+
 ## 📋 Pull Request Checklist
 
 - [ ] Plugin directory created under `plugins/`
 - [ ] `.mcp.json` with valid MCP server configuration
 - [ ] `README.md` with installation instructions
 - [ ] `SKILL.md` with YAML frontmatter and documentation
-- [ ] Plugin registered in `.github/plugin/marketplace.json`
+- [ ] Plugin registered in both marketplace manifests; host plugin descriptions agree
 - [ ] Root `README.md` updated with new plugin entry
 - [ ] `PLUGINS.md` updated with new plugin entry, skills, and examples