SAN-1274 PR 1 — Add the verified MDE AI skills foundation

.claude/skills/cloudinary/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cloudinary
+description: >-
+  Use when MDE work explicitly introduces or changes Cloudinary uploads, assets, transformations, delivery URLs, signatures, webhooks, or media lifecycle behavior.
+---
+
+# Cloudinary
+
+Own Cloudinary-specific media behavior. Do not assume Cloudinary is active merely because the project may use media assets.
+
+## Current-state rule
+
+The current repo has no direct Cloudinary dependency or active source reference in the audited application paths. First verify that the task actually uses Cloudinary. If not, do not introduce it as architecture by default.
+
+## Invariants
+
+- Keep API secrets and signing secrets server-side.
+- Prefer signed uploads/transformations when the operation requires trust.
+- Validate resource ownership before destructive asset changes.
+- Keep durable application metadata in the application database; Cloudinary is media infrastructure, not the business source of truth.
+- Verify webhook signatures before applying side effects.
+
+## Workflow
+
+1. Confirm Cloudinary is in scope and inspect any existing integration.
+2. Verify the current official API/SDK contract.
+3. Define upload, transformation, deletion, and failure behavior.
+4. Implement only the required integration surface.
+5. Test invalid signatures, missing assets, and retry behavior when applicable.
+
+## Handoff
+
+Use `nextjs` for framework upload routes, `supabase` for application metadata/authorization, and the owning domain skill for product behavior.

.claude/skills/cloudinary/evals/evals.json

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "evals": [
+    {
+      "prompt": "Handle a focused cloudinary change in MDE and identify the correct implementation boundary.",
+      "expected_output": "Uses cloudinary as the primary specialist and keeps unrelated domains out.",
+      "expectations": [
+        "inspects current repo state",
+        "uses current official docs for version-sensitive behavior",
+        "makes the smallest safe change"
+      ]
+    },
+    {
+      "prompt": "A bug appears near cloudinary, but the root cause is not known. What owns diagnosis?",
+      "expected_output": "Routes diagnosis to systematic-debugging while retaining the specialist for domain evidence.",
+      "expectations": [
+        "does not guess root cause",
+        "uses systematic-debugging for diagnosis",
+        "keeps specialist scope bounded"
+      ]
+    },
+    {
+      "prompt": "A production-critical cloudinary change is ready to ship. What proof is required?",
+      "expected_output": "Requires targeted tests and independent task verification before Done.",
+      "expectations": [
+        "requires current evidence",
+        "does not self-certify",
+        "uses task-verifier for completion proof"
+      ]
+    }
+  ]
+}

.claude/skills/copilotkit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: copilotkit
+description: >-
+  Use when MDE work involves CopilotKit, /api/copilotkit, CopilotKit v2 React hooks, generative UI, frontend tools or actions, shared agent state, AG-UI transport, runtime wiring, CLI verification, HITL, or the CopilotKit-to-Mastra bridge.
+metadata:
+  mde-version: "2.0.0"
+  upstream-commit: "8a7446186cd3e0d368ec885e61c5913f0918ef5d"
+  verified-package: "@copilotkit/react-core 1.55.2 / @copilotkit/runtime 1.55.2"
+---
+
+# CopilotKit — official upstream + MDE overlay
+
+## Source order
+
+1. Inspect the installed MDE CopilotKit packages and current runtime/provider code.
+2. Read the pinned official CopilotKit core skill in `references/official/copilotkit/SKILL.md`.
+3. For wiring/debugging, also read `references/official/copilotkit-cli/SKILL.md` and run `npx copilotkit@latest verify --json` when safe and applicable.
+4. Use current official CopilotKit/AG-UI docs or source when the pinned skill directs you there.
+5. Apply the MDE-specific invariants below.
+
+Do not answer volatile CopilotKit API questions from memory. Do not silently replace installed-version behavior with latest-main examples.
+
+## Ownership
+
+Own the browser-facing agent bridge: provider/hooks, same-origin runtime, AG-UI events, frontend tool/action registration, shared state, generative UI, and CopilotKit-visible failures. `mastra` owns agents/tools/workflows/memory/storage/HITL semantics. Product-domain skills own business invariants.
+## Current MDE invariants
+
+- MDE uses CopilotKit v2 React APIs from `@copilotkit/react-core/v2`.
+- Browser traffic uses the same-origin `/api/copilotkit` runtime; do not switch to hosted Intelligence implicitly.
+- Tool render/action names must match the Mastra tool-map key, not a `createTool()` id.
+- Preserve auth, distributed rate limits, request context, telemetry, and agent allowlists on the runtime route.
+- Treat AG-UI messages/events as the frontend-agent transport contract; do not create parallel ad-hoc chat state.
+- Keep provider props stable across renders.
+
+## Workflow
+
+1. Classify the issue: wiring/runtime, React/provider, AG-UI/tool rendering, shared state, CLI verification, or Mastra bridge.
+2. Use the official core/CLI skill as the default procedure and lookup guide.
+3. Load only the matching MDE reference: `runtime-and-react.md`, `ag-ui-and-tools.md`, or `mastra-bridge.md`.
+4. Reproduce before editing when debugging.
+5. Keep the smallest safe contract change and hand Mastra-internal changes to `mastra`.
+6. Prove the affected contract with targeted tests plus browser/stream evidence when user-visible behavior changed.
+
+## Verification
+
+At minimum verify the affected runtime URL, agent identity, version surface, tool/action mapping, auth/rate-limit behavior, AG-UI result/state handling, and rendered user path. A passing CopilotKit CLI wiring check does not prove tool execution, streaming order, state synchronization, or rendered generative UI; test those separately.
+
+## References
+
+- `upstream.yaml` — immutable source provenance and update policy
+- `references/official/copilotkit/SKILL.md` — official vendor skill, pinned and read-only
+- `references/official/copilotkit-cli/SKILL.md` — official CLI skill, pinned and read-only
+- `references/runtime-and-react.md`
+- `references/ag-ui-and-tools.md`
+- `references/mastra-bridge.md`
+- https://docs.copilotkit.ai/
+- https://github.com/CopilotKit/CopilotKit

.claude/skills/copilotkit/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "copilotkit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "The /api/copilotkit stream is returning 500 after a runtime change. Diagnose the CopilotKit side without rewriting Mastra tools.",
+      "expected_output": "Routes to CopilotKit plus systematic debugging; verifies installed v2/runtime wiring and current official sources before proposing a change.",
+      "files": [],
+      "expectations": [
+        "Uses CopilotKit for the browser/runtime boundary",
+        "Verifies installed/current source rather than answering volatile API details from memory",
+        "Does not rewrite Mastra tool business logic"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "A Mastra search tool executes successfully but the CopilotKit v2 card never renders. What should we verify?",
+      "expected_output": "Checks frontend action/tool registration against the Mastra tool-map key, AG-UI result flow, and rendered browser path.",
+      "files": [],
+      "expectations": [
+        "Checks the CopilotKit action/tool-name contract",
+        "Checks AG-UI/tool result handling",
+        "Requires browser-visible proof, not only a tool unit test"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "The event host publishing rule needs to change from draft-only to draft-or-reviewed.",
+      "expected_output": "Does not select CopilotKit as the owner because this is a product-domain rule with no CopilotKit dependency.",
+      "files": [],
+      "expectations": [
+        "Does not treat CopilotKit as the primary owner",
+        "Routes to the relevant product/domain workflow instead"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Can we copy a CopilotKit main-branch example into our app? We are on @copilotkit/react-core 1.55.2.",
+      "expected_output": "Checks installed package/version and pinned/current official source first; preserves v2 import/runtime contract and refuses blind latest-main copying.",
+      "files": [],
+      "expectations": [
+        "Checks installed version before using examples",
+        "Does not blindly substitute latest-main API behavior",
+        "Preserves the v2 surface when applicable"
+      ]
+    }
+  ]
+}

.claude/skills/copilotkit/references/ag-ui-and-tools.md

@@ -0,0 +1,7 @@
+# AG-UI and frontend tools
+
+CopilotKit v2 uses AG-UI as the agent/user interaction transport. Treat text streaming, tool calls/results, and state snapshots/deltas as protocol contracts.
+
+MDE-specific rule: CopilotKit tool/action names align to Mastra tool map keys. Verify `src/platform/copilot/mastra-tool-action-names.ts` and its tests before changing render/action registration.
+
+When tool result envelopes or state change, test normalization plus the rendered browser path; protocol-shape tests alone do not prove UI behavior.

.claude/skills/copilotkit/references/mastra-bridge.md

@@ -0,0 +1,11 @@
+# CopilotKit ↔ Mastra bridge
+
+MDE uses `@ag-ui/mastra` adapters behind the CopilotKit runtime. CopilotKit owns transport/UI registration; `mastra` owns agent definitions, tool implementations, workflows, memory, persistence, and HITL semantics.
+
+Before changing the bridge inspect:
+- `src/mastra/copilotkit/logging-mastra-agent.ts`
+- `src/platform/copilot/mastra-tool-action-names.ts`
+- the `/api/copilotkit` route
+- current Mastra agent registry/allowlist
+
+Do not duplicate Mastra business/tool logic in React actions. Preserve request/tenant context and telemetry across the bridge.

.claude/skills/copilotkit/references/official/copilotkit-cli/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: copilotkit-cli
+description: "Use for the CopilotKit CLI — `npx copilotkit@latest`. Covers proving a project's wiring with `verify` before debugging anything by hand, scaffolding with `create`, signing in and selecting a hosted Intelligence project, agent-assisted onboarding of an existing app, generating type-safe agent ids, and importing thread history. Reach for `verify` first whenever a CopilotKit app is not working."
+version: 1.0.0
+---
+
+# CopilotKit CLI
+
+```bash
+npx copilotkit@latest <command>
+```
+
+`--help` on any command prints its flags. The commands below are the ones worth knowing
+before you start reading someone's project by hand.
+
+## `verify` — do this before debugging
+
+```bash
+npx copilotkit@latest verify --json
+```
+
+One command replaces the manual survey. It settles up to eleven things: a hosted project is
+selected; the project API key is present, loadable by the app, and authenticates; the runtime
+responds, declares an agent, actually consumes the credential, and serves the thread routes;
+the frontend serves its own assets; the runtime accepts the browser's origin; and the
+installed CopilotKit packages match the version the runtime reports. It also reports the
+runtime version, the agent framework in use, whether transcription is wired, the realtime
+gateway wiring, and the license state.
+
+Eleven is the ceiling, not a promise. The last three are omitted when there was nothing to
+check them against — no frontend origin was found, or no installed packages were. Count
+`checks[]` rather than assuming a fixed set. With `--expect-runtime oss` the hosted-project
+and credential checks do not apply at all, so that run is a smaller set.
+
+Crucially it names **which URL it probed and where that URL came from** — the project's
+`runtimeUrl`, an environment variable, the app's own dev configuration, or an assumed
+default. A survey done by hand cannot tell you that, and the provenance changes the verdict:
+nothing answering at a URL **the project named** is a FAIL, while nothing answering at an
+**assumed** default is UNKNOWN, because an app on a port the command never learned is not a
+wiring failure.
+
+Useful flags:
+
+- `--frontend-url <origin you actually open>` — adds the browser-facing checks, including a
+  real CORS preflight when that origin differs from the runtime's
+- `--round-trip` — also runs the agent and reads its answer back. Costs a model call, so it
+  is opt-in
+- `--expect-runtime oss` — for a self-hosted runtime with no Intelligence. It exits zero
+  only when `/info` declares the named agent, reports no Intelligence entitlement, and
+  `--round-trip --agent <id>` passes
+- `--agent <id>` — which declared agent to run, when several are registered
+- `--runtime-url <url>` — probe this endpoint instead of the one read from the project
+- `--header '<name>: <value>'` — repeatable. Needed when the project's `identifyUser` reads
+  a session the CLI does not carry
+- `--timeout <seconds>` — how long to wait for an answer, default 90
+
+Read `checks[]` and fix in the order given:
+
+- The checks **chain**. A later check that could not run says so and names the earlier one to
+  fix first, so the first failure is the real one.
+- `UNKNOWN` means the check could not run. It never means the check passed, and the command
+  exits non-zero unless every check passed.
+
+### What `verify` does not cover
+
+Reach past it only once it is clean.
+
+- **Tool execution.** `--round-trip` deliberately asks a question that needs no tools and
+  sends no context, so a passing round trip says nothing about whether your tools work.
+- **Event ordering and streaming.** It reports pass or fail on a run, not the sequence inside
+  it. A run that starts and never finishes, or stalls mid-stream, is a job for the Inspector.
+- **State synchronisation.** Snapshot-versus-delta divergence is agent behaviour, not wiring.
+
+## Starting a project
+
+```bash
+npx copilotkit@latest init          # `create` is an alias for it
+```
+
+Prompts for a name and framework, scaffolds a starter, signs you in when needed, and connects
+the app to a cloud-hosted Intelligence project. The name it asks for names the new directory,
+so this is the path for a project that does not exist yet. For an app you already have, use
+`onboard start` below.
+
+To add CopilotKit to an existing app, either follow the [quickstart](/quickstart), or hand
+the job to your coding agent:
+
+```bash
+npx copilotkit@latest onboard start
+```
+
+That runs an agent-guided flow over the repository you are already in, with checkpoints and
+proof steps rather than a scaffold. `onboard start --intent <feature>` targets one feature on
+an app that already has CopilotKit.
+
+## Signing in and picking a project
+
+```bash
+npx copilotkit@latest login --json   # agent-readable JSON lines, no browser launch
+npx copilotkit@latest login          # interactive: opens a browser
+npx copilotkit@latest whoami         # who is signed in, and the active organization
+npx copilotkit@latest project select # pick or create a hosted project for this directory
+npx copilotkit@latest project list --json
+```
+
+Use `login --json` when you are driving the CLI. Bare `login` tries to open a browser, which
+is not something you can complete.
+
+There is no `auth` command. It is `login`.
+
+`project select` records the choice in `.copilotkit/project.json` and provisions a
+project-scoped runtime key into `.env`:
+
+```
+CPK_INTELLIGENCE_API_KEY=cpk_...
+```
+
+`CPK_INTELLIGENCE_API_KEY` is the canonical name and the only one the CLI writes. Keep it
+server-side — it is a runtime key, not a frontend token, so it takes **no** `NEXT_PUBLIC_` or
+`VITE_` prefix. Do not set the platform URLs: they default to the managed hosts, so any value
+you supply can only replace a correct default with a worse one.
+
+Without a TTY — which is what a coding agent has — use `project list --json` to see the
+choices and `project select --project <id>` or `--create <name>` to name the answer up front.
+
+## Other commands
+
+| Command                                    | What it does                                                                   |
+| ------------------------------------------ | ------------------------------------------------------------------------------ |
+| `skills install`                           | Installs these skills into a project (`skills onboard` also starts onboarding) |
+| `typegen`                                  | Generates type-safe agent ids from a running runtime                           |
+| `import --source adk\|langgraph --dry-run` | Previews importing historical threads into Intelligence                        |
+| `license create` / `license list`          | Issues and lists license tokens                                                |
+| `channels`                                 | Sets up managed Intelligence Channels for Slack or Microsoft Teams             |
+| `framework list`                           | The agent frameworks `create` accepts, and their flags                         |
+| `logs`                                     | The CLI log path, or recent lines                                              |
+| `telemetry`                                | Shows or changes the CLI telemetry preference                                  |
+| `docs`                                     | Opens the documentation                                                        |
+| `version`                                  | Version, build, and commit                                                     |
+
+The CLI collects usage data. `DO_NOT_TRACK=1` or `COPILOTKIT_TELEMETRY_DISABLED=1` opts out.