codeapp-js 0.3.0 → 1.0.0

package/AI/codeapp.agent.md

@@ -0,0 +1,105 @@
+---
+name: codeapp
+description: This custom agent helps users rapidly prototype and build Power Apps using a code-first approach.
+argument-hint: Create a codeapp that uses the code-first approach to build Power Platform apps. This agent uses JavaScript, HTML, and CSS, and is ideal for users who want to rapidly prototype and build Power Apps using standard web technologies, with built-in support for Dataverse, connectors, and Power Platform workflows.
+---
+
+You are **Code App Plus**, an expert AI coding agent specializing in Microsoft Power Platform code-first development. You are an AGENT — you don't just suggest code, you directly create and edit files in the user's workspace.
+
+## Your Expertise
+- Building Power Apps using the code-first SDK (HTML, CSS, JavaScript)
+- Dataverse table design, CRUD operations, and lookup relationships
+- Power Platform connectors: SharePoint, Outlook, Office 365 Users, Office 365 Groups
+- Built-in extension workflows: auth, environment management, connection sync, and deploy
+- Environment variables in Dataverse
+- Progressive Web App patterns for Power Platform apps
+
+
+## How You Work
+1. When the user asks you to build something, use createFile to create the files directly.
+2. When the user asks you to add new code to an existing file, use appendFile or insertBefore.
+3. Never use editFile, writeFile, or insertBefore on a file you have not read yet.
+4. When the user reports a bug or asks for a fix, read the related files first, then make the change.
+5. Before using a connector or building a feature that has a matching skill, use readSkill to load the full skill document first. Do not guess connector patterns — read the skill and connector js file.
+6. If a **New Project Setup** skill section is present in the system context, you MUST follow its instructions before building anything. This takes priority over all other rules.
+7. When interactive user input is available, ask the required questions through the interactive question flow and continue in the same session after the user answers.
+Only stop and end the turn when interactive user input is not available.
+8. During process update `agent/decision-log.md` with your plan and: important decisions, constraints, bug fixes, and what files have been updated with new/delete row count.  Do not store chat transcripts, code dumps, or temporary notes.
+9. Review the persistent decision log at `agent/decision-log.md` before acting.
+10. After making changes, provide a brief summary.
+11. Before asking the user a clarification question, check whether the answer is already fixed by `power.config.json`, the loaded skills, the current workspace files, or the agent instructions. If it is, use that answer and do not ask.
+
+## Task Tracking with TODO Lists
+- For multi-step tasks, create a TODO checklist in `agent/decision-log.md` under the `## TODO` section.
+- Format: `- [ ] description` for pending, `- [x] description` for complete.
+- If the **New Project Setup** skill applies, the TODO must explicitly include the gating setup steps before build work starts: confirm or choose the visual theme/colours, offer mockups if none exist, create mockups if the user says yes, and only then proceed to implementation.
+- Update the TODO list after completing each significant step (mark items `[x]`).
+- If the conversation hits a token limit and you are restarted in a new chat, read `agent/decision-log.md` first. The `## TODO` section tells you what remains.
+- When all TODOs for a task are complete, remove them from the list to keep the file terse.
+
+## Recovering After Token Limits
+- If you encounter context-length errors or are told the previous session hit a token limit, immediately read `agent/decision-log.md`.
+- Check the `## TODO` section and resume from the first unchecked item.
+- Do not re-do work already marked `[x]`.
+- Begin your response with a brief status: which TODOs are done and which you will tackle now.
+
+## Mockup-to-Build Workflow
+When the user picks a mockup from `agent/` to implement:
+1. Read the chosen mockup file.
+2. Keep the original user request, accepted requirements, and decision-log TODOs in scope. The mockup choice refines the design direction; it does not replace the original build task.
+3. Use its full content as the **starting base** for `createFile` — copy the HTML/CSS/JS directly into each target `dist/` file.
+4. Then use `editFile` to adapt the copied content (replace placeholder data with live connector calls, adjust paths, etc.).
+5. Do NOT treat the mockup as mere inspiration or context. Copy as much of the original markup, styles, and structure as possible so the build is faithful to the chosen design.
+6. Break large files across multiple tool calls (createFile for a skeleton, then appendFile for sections) to avoid truncation.
+7. If the startup skill asked you to create mockups, those mockup files must actually be written to `agent/` before you say they are available.
+8. Mockups in `agent/` are standalone one-page HTML prototypes. They must open directly in a browser, include inline or linked CSS plus lightweight JavaScript interaction, and must never be delivered as Markdown.
+9. When creating multiple mockups or other ordered artifacts, complete each file fully before moving to the next one. Do not design all options first and only write files at the end.
+
+## Critical Rules
+- You are an AGENT — take action.
+- Read before you edit.
+- Never overwrite a file with partial content.
+- Prefer appendFile and insertBefore over editFile when adding code.
+- Use writeFile for JSON config files after reading them.
+- For ordered multi-file work, perform tool calls sequentially in creation order. If you are making five mockups, create mockup 1 before starting mockup 2, and continue one file at a time.
+- Keep persistent memory short and precise. Prefer replacing stale bullets over adding noisy ones.
+
+## Response Format
+- Start with a one-line summary, then include tool blocks.
+- Never respond with only text in agent mode — EXCEPT when the New Project Setup skill requires you to ask the user a question and interactive user input is not available. In that case, ask the question and STOP without any tool calls.
+- After the tool blocks, provide a brief summary of changes and any next steps.
+
+## Key rules
+- ***DO NOT*** use external sources like google fonts
+- Use relevant skill files from the skills folder
+- Standard web technologies: HTML, CSS, JavaScript (ES6+).
+- All code that is required on start/load should be called in the boot function, all html inside the div id="root"
+- Only use`fetch` if not a Microsoft service and there are not function files use fetch, but warn the user that you are using fetch and it may be broken by Content Security Policy. Always try to use `codeapp.js` functions.
+- If `power.config.json` includes `appDisplayName`, use it as the app name by default and update the index.html title with it. Do not ask the user to supply a name unless they explicitly want to rename the app.
+- If `power.config.json` or the selected skills indicate the Outlook connector (`shared_office365`, `office365`, `office365-outlook`), assume Microsoft 365 / Outlook. Do not ask the user to choose an email provider unless their request explicitly asks for a different one.
+- When scaffolding or fixing an app that uses a managed connector, verify the required functions exist in `codeapp.js` or the relevant SDK file before wiring `index.js`, ***do not create your own functions, import from codeapp.js***.
+- The agent should not drive PAC CLI directly from chat for managed connector setup. If the user reports connector setup problems, direct them to the built-in Auth, Environment, Sync Connections, or Deploy buttons as appropriate.
+
+## Project Overview
+- Use HTML, CSS, and JavaScript in `dist/` to create a Micrsoft Power App CodeApp, do not ask the user whether they want React, Vue, or another framework. 
+- Shipped app implementation files live in the `dist/` directory. Startup workflow artifacts may also live in `agent/`:
+  - `agent/decision-log.md`
+  - `agent/mockup-1.html` through `agent/mockup-5.html` (or similar mockup names)
+- If you need to write startup artifacts under `agent/`, ensure `agent/` exists as a directory first. Never create a plain file named `agent`.
+- App implementation files in `dist/` must stay there:
+  - `index.html`-single allowed page
+  - `index.js`- only allowed file for new javascript code
+  - `codeapp.js`-helper library containing reusable functions, debugger, and utility functions
+  - `sharepoint.js`-sdk for sharepoint
+  - `outlook.js`-sdk for outlook
+  - `office365users.js`-sdk for office 365 users
+  - `office365groups.js`-sdk for office 365 groups
+  - `teams.js`-sdk for teams
+  - `dataverse.js`-sdk for dataverse
+  - `jira.js`-sdk for jira
+  - `keyvalue.js`-sdk for keyvault
+  - `power-apps-data.js`-sdk for power apps
+- `power-config.json`-config file for when publishing to environment, this is not in the dist directory
+- `codeapp.js` is the helper pre-built library — NEVER modify it. Import its functions into `index.js` when needed.
+
+

package/AI/skills/connections/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: connections
+description: "Use when: wiring connector-backed Power Apps Code Apps, validating connectionReferences or dataSources names, or debugging handwritten connector wrappers. Load alongside connector-specific skills."
+---
+
+# Connections Guide
+
+Use this skill for the shared rules that apply across the handwritten connector helpers in `dev files/`.
+
+## Core Rules
+
+All authentication is handled by the Power Apps runtime and the connector client.
+
+Do:
+- Keep connector calls inside the wrapper helper for that connector.
+- Reuse the repo's helper patterns such as `unwrapResult` and the candidate data-source retry logic in `codeapp-helper.js`.
+- Treat the helper file as the repo-local source of truth for public function names, default versions, and parameter mapping.
+- Validate `power.config.json` `dataSources` names against the wrapper before changing them.
+
+Don't:
+- Don't add MSAL, custom token acquisition, or manual `Authorization` headers.
+- Don't call Dataverse or Microsoft Graph directly when the repo already exposes a connector helper.
+- Don't invent connector operation paths, header names, or parameter names.
+- Don't assume every connector uses the same raw HTTP helper shape.
+
+## Wrapper Patterns
+
+- `codeapp-helper.js` exposes `execConnectorOpWithCandidates(...)` for wrappers that must retry multiple `dataSources` names.
+- Some wrappers use exact inline `apis` metadata (`outlook.js`, `office365users.js`, `Teams.js`, `Jira.js`, `AzureKeyvault.js`).
+- Some wrappers intentionally rely on runtime-resolved connector operations and focus on stable public helper names (`office365groups.js`).
+- Prefer the existing wrapper over rebuilding a connector client from scratch unless the wrapper is missing the operation entirely.
+
+## Raw HTTP Helpers
+
+The raw HTTP helper signatures are not interchangeable.
+
+- Outlook, Office 365 Users, and Office 365 Groups map friendly inputs to connector fields like `Uri`, `Method`, `Body`, `ContentType`, and `CustomHeader1..5`.
+- SharePoint and Teams currently pass `method`, `uri`, `headers`, and `body` directly.
+
+Check the specific wrapper before copying a raw-request pattern between connectors.
+
+## Review Checklist
+
+- Keep `tableName` aligned with the wrapper's supported `dataSources` names.
+- Preserve existing public helper names and widen inputs with options objects instead of breaking positional calls.
+- Normalize SDK envelopes before returning data to app code.
+- Prefer repo helpers over direct network code when a connector wrapper already exists.

package/AI/skills/dataverse/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: dataverse
+description: "Use when: building or debugging Dataverse CRUD in a Power Apps Code App, registering tables with initDataSources or registerTable, calling callUnboundAction, or using whoAmI and Dataverse-backed environment variables."
+---
+
+# Dataverse Guide
+
+> Prerequisite: load the `connections` skill for the shared auth and wrapper rules.
+
+## power.config.json
+
+For the helper in `dev files/codeapp-helper.js`, Dataverse CRUD depends on `databaseReferences.default.cds.dataSources`.
+
+```json
+{
+  "databaseReferences": {
+    "default.cds": {
+      "dataSources": {
+        "accounts": {
+          "entitySetName": "accounts",
+          "logicalName": "account",
+          "isHidden": false
+        }
+      }
+    }
+  }
+}
+```
+
+- `entitySetName` is the plural OData collection name.
+- `logicalName` is the singular logical name.
+- Every Dataverse table used by the app must be present here.
+- Do not add unbound actions like `WhoAmI` or `GrantAccess` to `dataSources`.
+
+The helper does not require a separate Dataverse `connectionReferences` entry for CRUD or `callUnboundAction`.
+
+## Table Registration
+
+The helper supports both `initDataSources(...)` and `registerTable(...)`.
+
+Use `initDataSources(...)` before the first Dataverse call when you know the full table set up front.
+
+```js
+import { initDataSources } from './codeapp.js';
+
+function dsEntry(sPrimaryKey) {
+  return { tableId: '', version: '', primaryKey: sPrimaryKey, dataSourceType: 'Dataverse', apis: {} };
+}
+
+initDataSources({
+  accounts: dsEntry('accountid'),
+  contacts: dsEntry('contactid')
+});
+```
+
+Use `registerTable(tableName, primaryKey)` only when you need to add a table at runtime. It resets the cached client.
+
+## CRUD Surface
+
+`codeapp-helper.js` exports:
+
+- `createItem(tableName, primaryKey, record)`
+- `getItem(tableName, primaryKey, id, select)`
+- `listItems(tableName, primaryKey, options)`
+- `updateItem(tableName, primaryKey, id, changedFields)`
+- `deleteItem(tableName, primaryKey, id)`
+
+Notes:
+
+- `listItems(...)` returns `{ entities: [...] }`.
+- `select` and `orderBy` accept arrays or comma-separated strings.
+- `whoAmI()` reads the Power Apps context with `getContext()`; it does not call a Dataverse action.
+
+## Unbound Actions
+
+`callUnboundAction(tableName, primaryKey, actionName, params)` uses `callActionAsync(...)` under the hood.
+
+- It requires at least one real Dataverse table to be registered so the helper can resolve the environment.
+- Do not add action names to `power.config.json`.
+- Standard Dataverse actions still need correct complex parameter payloads such as `@odata.type` annotations.
+
+## Environment Variables
+
+`getEnvironmentVariable(schemaName)` is part of the same helper file.
+
+- Add `environmentvariabledefinitions` and `environmentvariablevalues` to `databaseReferences.default.cds.dataSources`.
+- Include those tables in `initDataSources(...)` or register them before the first read.
+
+## Relationship Tips
+
+- Write lookups with `'<navProperty>@odata.bind': '/<entitySet>(<guid>)'`.
+- Read lookup IDs with the `_<name>_value` pattern.
+
+## Common Failures
+
+- `DataSourceNotFound`: the table is missing from `power.config.json`, `initDataSources(...)`, or runtime registration.
+- `Invalid property 'xyz'`: the column name is wrong.
+- `Entity 'xyz' does not exist`: the entity set name is wrong.
+- Single-record retrieve can fail for some tables such as `entities`; use `listItems(...)` with a filter instead.

package/AI/skills/environment-variables/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: environment-variables
+description: "Use when: wiring Dataverse environment variables into a Power Apps Code App, asking for schema names, updating power.config.json table references, or reading values with getEnvironmentVariable from codeapp.js."
+---
+
+# Environment Variables Guide
+
+> Agent limitation: do not create maker-portal environment variables from chat. The user creates them; the app only reads them.
+
+## Workflow
+
+1. Ask the user for the exact schema names that already exist in the maker portal.
+2. Read `power.config.json` before editing it.
+3. Add the two Dataverse tables used by environment variables.
+4. Wire `getEnvironmentVariable(...)` into the app startup code.
+
+## power.config.json
+
+Add both tables under `databaseReferences.default.cds.dataSources`.
+
+```json
+{
+  "databaseReferences": {
+    "default.cds": {
+      "dataSources": {
+        "environmentvariabledefinitions": {
+          "entitySetName": "environmentvariabledefinitions",
+          "logicalName": "environmentvariabledefinition",
+          "isHidden": false
+        },
+        "environmentvariablevalues": {
+          "entitySetName": "environmentvariablevalues",
+          "logicalName": "environmentvariablevalue",
+          "isHidden": false
+        }
+      }
+    }
+  }
+}
+```
+
+Do not add a custom `environmentVariables` key to `power.config.json`.
+
+## Helper Surface
+
+The repo reads environment variables through `getEnvironmentVariable(...)` in `codeapp.js` / `codeapp-helper.js`.
+
+There is no separate `environmentVar.js` helper in `dev files/`.
+
+If the app already uses `initDataSources(...)`, add both environment-variable tables there.
+
+```js
+import { initDataSources, getEnvironmentVariable } from './codeapp.js';
+
+function dsEntry(sPrimaryKey) {
+  return { tableId: '', version: '', primaryKey: sPrimaryKey, dataSourceType: 'Dataverse', apis: {} };
+}
+
+initDataSources({
+  environmentvariabledefinitions: dsEntry('environmentvariabledefinitionid'),
+  environmentvariablevalues: dsEntry('environmentvariablevalueid')
+});
+```
+
+If the app does not use `initDataSources(...)`, register both tables before the first `getEnvironmentVariable(...)` call.
+
+## Value Formats
+
+- Text, number, and boolean variables come back as strings.
+- Data Source variables come back as JSON strings and must be parsed.
+
+```js
+const sSiteJson = await getEnvironmentVariable('wd_sharepointsite');
+const oSite = JSON.parse(sSiteJson);
+const sSiteUrl = oSite.SiteUrl;
+```
+
+## Summary Rules
+
+- Ask for schema names; do not invent them.
+- Keep the env-var tables in the same Dataverse table setup as the rest of the app.
+- Import `getEnvironmentVariable(...)` from `./codeapp.js`.
+- Parse Data Source values before using them.
+
+## Common Failures
+
+- `Data source not found ... environmentvariabledefinitions`: the two Dataverse tables are missing from `power.config.json` or the helper registration.
+- `Environment variable not found: xyz`: the schema name is wrong or missing in Dataverse.
+- Empty string: neither a current value nor a default value exists.

package/AI/skills/frontend-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: frontend-design
+description: "Use when: designing or restyling pages, components, mockups, dashboards, or app UIs in this repo. Favor distinctive frontend work over generic defaults."
+---
+
+# Frontend Design Guide
+
+Use this skill to keep UI work intentional, distinctive, and production-grade.
+
+## Design Thinking
+
+Before coding:
+
+- Understand the purpose, audience, and constraints.
+- Commit to a clear aesthetic direction instead of blending safe defaults.
+- Treat the existing workspace configuration and loaded skills as the source of truth for stack and app constraints.
+- Default to plain HTML, CSS, and JS when the repo does not require a framework.
+
+## Aesthetic Rules
+
+- Choose fonts with character. Avoid default system-looking results.
+- Use a deliberate palette with clear hierarchy and CSS variables.
+- Build atmosphere with gradients, textures, overlays, or shape systems instead of flat backgrounds.
+- Use motion for a few strong moments rather than generic micro-animations everywhere.
+- Make layouts feel designed, not template-generated.
+
+## Avoid
+
+- Generic AI-looking typography and spacing.
+- Purple-on-white gradient defaults.
+- Cookie-cutter cards and dashboards with no point of view.
+- Asking the user to pick a framework when the repo already implies one.
+
+Push for work that feels specific to the app instead of interchangeable.

package/AI/skills/jira/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: jira
+description: "Use when: building or debugging Jira connector flows in a Power Apps Code App, including jiraInstance-aware helpers, issue or project operations, task operations, or Jira MCP actions."
+---
+
+# Jira Connector Guide
+
+> Agent limitation: do not use CLI commands directly from chat for Jira setup. Use the built-in Sync Connections and Deploy buttons instead.
+
+## Core Rule
+
+The wrapper in `dev files/jira.js` is the repo-local source of truth for public helper names and defaults.
+
+- It retries the data-source names `jira`, `Jira`, and `JIRA`.
+- It includes inline connector metadata for the operations the wrapper supports.
+- Many helpers switch between non-instance and instance-aware variants depending on whether `jiraInstance` is supplied.
+
+## power.config.json
+
+Prefer a Jira connection reference whose `dataSources` array includes `jira`.
+
+```json
+{
+  "connectionReferences": {
+    "jiraConnection": {
+      "id": "/providers/Microsoft.PowerApps/apis/shared_jira",
+      "displayName": "Jira",
+      "dataSources": ["jira"],
+      "authenticationType": "APIToken",
+      "dataSets": {}
+    }
+  }
+}
+```
+
+## Public Helper Surface
+
+`Jira.js` exports stable helpers such as:
+
+- `listJiraIssues(...)`
+- `getJiraIssueByKey(...)`
+- `addJiraComment(...)`
+- `createJiraIssue(...)`
+- `createJiraIssueV3(...)`
+- `editJiraIssue(...)`
+- `updateJiraIssue(...)`
+- `listJiraProjects(...)`
+- `createJiraProject(...)`
+- `updateJiraProject(...)`
+- `deleteJiraProject(...)`
+- `getJiraTask(...)`
+- `cancelJiraTask(...)`
+- `getCurrentJiraUser(...)`
+- `getJiraUser(...)`
+- `listJiraIssueTypes(...)`
+- `listJiraStatuses(...)`
+- `manageJiraIssues(queryRequest, sessionId)`
+
+## Important Wrapper Behavior
+
+- Passing `jiraInstance` makes the wrapper inject `X-Request-Jirainstance` and choose the instance-aware operation when one exists.
+- `cancelJiraTask(...)` sends `X-Atlassian-Token` and defaults it to `nocheck` when no token is provided.
+- `listJiraProjects(...)` uses `ListProjects_V2` without an instance and `ListProjects_V3` with an instance.
+- `createJiraIssue(...)` chooses between `CreateIssue`, `CreateIssueV2`, and `CreateIssue_V3` based on the provided options.
+
+## Raw Operation Notes
+
+If you need a raw connector call, use `callJiraOperation(operationName, parameters)` and preserve the exact connector field names.
+
+Do not guess:
+
+- operation names
+- path shapes
+- Jira instance header names
+- query field names like `issueTypeIds`, `notifyUsers`, or `overrideEditableFlag`
+
+## Debugging
+
+- If the failure mentions missing `path`, the inline metadata is incomplete or the wrong operation name is being used.
+- If the failure mentions Jira instance validation, check whether the helper expects `jiraInstance` and whether the wrapper selected the correct variant.
+- Use generated schema or service files only as supporting references; the repo wrapper controls the public API used by apps in this repo.

package/AI/skills/office365-groups/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: office365-groups
+description: "Use when: building or debugging Office 365 Groups connector flows in a Power Apps Code App, including group listing, membership, events, or openGroupsHttpRequest."
+---
+
+# Office 365 Groups Connector Guide
+
+> Agent limitation: do not use CLI commands directly from chat for Office 365 Groups setup. Use the built-in Sync Connections and Deploy buttons instead.
+
+## Core Rule
+
+The wrapper in `dev files/office365groups.js` is the repo-local source of truth.
+
+- It retries both `office365groups` and `Office365Groups`.
+- It keeps the public helper surface stable even though the raw connector operations are runtime-resolved.
+- Do not replace it with made-up placeholder paths copied from generic examples.
+
+## power.config.json
+
+Prefer a connection reference whose `dataSources` array includes `office365groups`.
+
+Older apps may still use `Office365Groups`; the wrapper retries both.
+
+## Public Helper Surface
+
+The wrapper exports:
+
+- `listMyGroups(options)`
+- `listOwnedGroups(options)`
+- `listGroups(options)`
+- `listGroupMembers(groupId, options)`
+- `onGroupMembershipChange(groupId, options)`
+- `addMemberToGroup(userUpn, groupId)`
+- `removeMemberFromGroup(userUpn, groupId)`
+- `createGroupEvent(groupId, options)`
+- `updateGroupEvent(eventId, options, groupId)`
+- `deleteGroupEvent(eventId, groupId)`
+- `onNewGroupEvent(groupId)`
+- `listDeletedGroups()`
+- `restoreDeletedGroup(groupId)`
+- `listDeletedGroupsByOwner(userId)`
+- `openGroupsHttpRequest(options)`
+
+## Important Wrapper Behavior
+
+- `listMyGroups({ version: 1|2|3 })` switches between `ListOwnedGroups`, `ListOwnedGroups_V2`, and `ListOwnedGroups_V3`.
+- `listGroups(...)` supports `$filter`, `$top`, `skipToken`, `nextLink`, and compatibility aliases like `skip`.
+- Event helpers accept flexible options objects and normalize event payloads for the connector.
+- `openGroupsHttpRequest(...)` maps friendly inputs to connector fields like `Uri`, `Method`, `Body`, `ContentType`, and `CustomHeader1..5`.
+- `openGroupsHttpRequest(...)` can target `HttpRequest` or `HttpRequestV2` with `version` or `useV2`.
+
+## Raw Calls
+
+Use `callGroupsOperation(operationName, parameters)` only when a high-level helper does not exist.
+
+Do not bypass the wrapper with direct Graph calls for operations already covered by the connector.
+
+## Debugging
+
+- If the failure is `Connection reference not found`, confirm the app exposes either `office365groups` or `Office365Groups` in `power.config.json`.
+- If an HTTP request fails, verify the wrapper is sending connector-style fields rather than raw fetch-style headers.

package/AI/skills/office365-outlook/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: office365-outlook
+description: "Use when: building or debugging Outlook connector flows in a Power Apps Code App, including mail, calendar, contacts, rooms, mailbox settings, or the repo Outlook helpers."
+---
+
+# Office 365 Outlook Connector Guide
+
+> Agent limitation: do not use CLI commands directly from chat for Outlook setup. Use the built-in Sync Connections and Deploy buttons instead.
+
+## Core Rule
+
+The wrapper in `dev files/outlook.js` is the repo-local source of truth, and `dev files/outlook-helper-reference.md` documents its accepted aliases.
+
+- It retries `office365outlook`, `Office365Outlook`, and `office365`.
+- It includes inline metadata for the operations the wrapper exposes.
+- Many helpers choose the operation version automatically.
+
+Prefer `office365` in `power.config.json`, while keeping the wrapper's candidate names intact.
+
+## Public Helper Surface
+
+The wrapper exports helpers for:
+
+- Mail: `sendEmail`, `listEmails`, `getEmail`, `forwardEmail`, `replyToEmail`, `moveEmail`, `deleteEmail`, `draftEmail`, `updateDraftEmail`, `sendDraftEmail`, `markEmailAsRead`, `updateEmailFlag`, `getEmailAttachment`, `assignOutlookCategory`, `assignOutlookCategoryBulk`
+- Shared mailbox: `sendFromSharedMailbox`
+- Calendar: `createEvent`, `listEvents`, `editEvent`, `deleteEvent`, `listCalendars`, `getEvent`, `getCalendarView`, `respondToEventInvite`, `findMeetingTimes`, `listRoomLists`, `listRooms`, `listRoomsInRoomList`, `setAutomaticReplies`, `getMailTips`
+- Contacts: `listContactFolders`, `listContacts`, `getContact`, `createContact`, `updateContact`, `deleteContact`
+- Advanced: `callOutlookOperation`, `callOutlookHttpRequest`, `manageOutlookEmails`, `manageOutlookMeetings`, `manageOutlookContacts`
+
+## Important Wrapper Defaults
+
+- `sendEmail(...)` uses `SendEmailV2` unless `isHtml === false`, in which case it uses the legacy plain-text action.
+- `listEmails(...)` defaults to version 3, folder `Inbox`, and `top: 10`.
+- `replyToEmail(...)` uses `ReplyToV3` unless `isHtml === false`.
+- `getEmail(...)` defaults to the V2 action.
+- `createEvent(...)`, `listEvents(...)`, and `editEvent(...)` use the V4 calendar actions.
+- `markEmailAsRead(...)` uses the V3 action unless the caller explicitly requests the older legacy pattern.
+
+## Raw HTTP Calls
+
+`callOutlookHttpRequest(...)` expects the connector-style field mapping used by the wrapper.
+
+- Pass `uri`, `method`, `body`, `contentType`, and `customHeaders`.
+- The wrapper maps them to `Uri`, `Method`, `Body`, `ContentType`, and `CustomHeader1..5`.
+
+Do not reuse the SharePoint or Teams raw HTTP pattern here.
+
+## Debugging
+
+- If the failure mentions `Connection reference not found`, verify `power.config.json` exposes one of the wrapper's candidate data-source names.
+- If a versioned mail or calendar call behaves unexpectedly, check the wrapper default before changing the raw operation name.
+- For alias-heavy helpers, consult `dev files/outlook-helper-reference.md` before adding new parameter mapping logic.

package/AI/skills/office365-users/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: office365-users
+description: "Use when: building or debugging Office 365 Users connector flows in a Power Apps Code App, including profiles, managers, direct reports, photos, searchForUsers, or openUsersHttpRequest."
+---
+
+# Office 365 Users Connector Guide
+
+> Agent limitation: do not use CLI commands directly from chat for Office 365 Users setup. Use the built-in Sync Connections and Deploy buttons instead.
+
+## Core Rule
+
+The wrapper in `dev files/office365users.js` is the repo-local source of truth.
+
+- It uses `office365users` as the connector data-source name.
+- It includes inline metadata for the supported operations.
+- It preserves older naming compatibility, but the main search operation used by the wrapper is `SearchUserV2`.
+
+## power.config.json
+
+Expose `office365users` in the connection reference `dataSources` array.
+
+```json
+{
+  "connectionReferences": {
+    "usersConnection": {
+      "id": "/providers/Microsoft.PowerApps/apis/shared_office365users",
+      "displayName": "Office 365 Users",
+      "dataSources": ["office365users"],
+      "dataSets": {}
+    }
+  }
+}
+```
+
+## Public Helper Surface
+
+The wrapper exports:
+
+- `getMyProfile(options)`
+- `getUserProfile(userId, options)`
+- `getManager(userId, options)`
+- `getDirectReports(userId, options)`
+- `getMyTrendingDocuments(options)`
+- `getTrendingDocuments(userId, options)`
+- `getRelevantPeople(userId)`
+- `updateMyProfile(profile)`
+- `updateMyPhoto(bodyOrOptions, contentType)`
+- `getUserPhotoMetadata(userId)`
+- `getUserPhoto(userId)`
+- `searchForUsers(options)`
+- `openUsersHttpRequest(options)`
+- `callUsersOperation(operationName, parameters)`
+
+## Important Wrapper Behavior
+
+- `select` can be an array or a comma-separated string.
+- `getDirectReports(...)` supports `top` and select options.
+- `searchForUsers(...)` uses `searchTerm`, `top`, `isSearchTermRequired`, and `skipToken`.
+- `searchForUsers(...)` accepts `nextLink` and legacy `skip` as compatibility inputs that the wrapper converts into `skipToken`.
+- `UserPhoto_V2` returns `image/jpeg`.
+
+## Raw HTTP Calls
+
+`openUsersHttpRequest(...)` does not use the simple `headers` object shape directly.
+
+The wrapper maps friendly inputs into connector fields:
+
+- `Uri`
+- `Method`
+- `Body`
+- `ContentType`
+- `CustomHeader1..5`
+
+## Debugging
+
+- If search pagination is broken, verify the code is passing `skipToken` or `nextLink`, not `$skip`.
+- If HTTP requests fail, check whether the wrapper is being fed connector-style fields through `openUsersHttpRequest(...)` rather than raw fetch options.
+- Keep the existing helper names stable and widen input support instead of replacing them.