@noodleseed/agent-kit 0.39.0 → 0.41.0

package/skills/claude-code/references/embedded-assistant.md

@@ -248,7 +248,125 @@ Or import the package root once and mount `<noodle-assistant session-endpoint="/
 
 The component renders a custom element and must mount client-side. In a Next.js App Router tree, put the mount in a `"use client"` component; from a server component or the Pages Router, load it with `next/dynamic` and `ssr: false`.
 
-For a customer-owned renderer, use the DOM-free client. It keeps the session token in memory, streams the same typed events, and never registers a custom element:
+For a customer-owned React renderer, use the renderer-free hook. It owns client lifetime and React subscription while `client` remains the one command surface:
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { useNoodleAssistant } from "@noodleseed/assistant/react/client";
+
+export function CustomAssistant({ principalKey }: { principalKey: string }) {
+  const [draft, setDraft] = useState("");
+  const { client, messages, status, error } = useNoodleAssistant({
+    sessionEndpoint: "/api/assistant/session",
+    principalKey,
+    clientContext: () => ({
+      locale: navigator.language,
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    }),
+  });
+  const busy = status === "submitted" || status === "streaming";
+  const settle = (operation: Promise<void>) => {
+    void operation.catch(() => {
+      // The hook exposes this same structured failure through `error`.
+    });
+  };
+
+  return (
+    <section aria-label="Assistant" aria-busy={busy}>
+      {messages.map((message) => (
+        <article key={message.id} data-role={message.role}>
+          {message.parts.map((part, index) => {
+            if (part.type === "text") return <p key={index}>{part.text}</p>;
+            if (part.type === "data-confirmation") {
+              const review = part.data;
+              return (
+                <section key={review.id} aria-label="Review proposed action">
+                  <h3>{review.title ?? "Review proposed action"}</h3>
+                  {review.description ? <p>{review.description}</p> : null}
+                  <pre aria-label="Proposed action arguments">
+                    {JSON.stringify(review.arguments ?? {}, null, 2)}
+                  </pre>
+                  <button
+                    disabled={busy || review.status !== "pending"}
+                    onClick={() => settle(client.respond(review.id, { action: "accept" }))}
+                  >
+                    Confirm
+                  </button>
+                  <button
+                    disabled={busy || review.status !== "pending"}
+                    onClick={() => settle(client.respond(review.id, { action: "decline" }))}
+                  >
+                    Don't proceed
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === "data-input-request") {
+              const request = part.data;
+              return (
+                <section key={request.id} aria-label="Assistant needs input">
+                  <p>{request.message}</p>
+                  <p>This renderer has not implemented the requested form.</p>
+                  <button
+                    disabled={busy || request.status !== "pending"}
+                    onClick={() => settle(client.respond(request.id, { action: "decline" }))}
+                  >
+                    Cancel request
+                  </button>
+                </section>
+              );
+            }
+            if (part.type === "data-tool-result") {
+              return (
+                <pre key={part.data.id} aria-label={`${part.data.tool} result`}>
+                  {JSON.stringify(part.data.result, null, 2)}
+                </pre>
+              );
+            }
+            if (part.type === "data-view") {
+              return (
+                <p key={part.data.id}>
+                  Trusted app view available: {part.data.title ?? part.data.resourceUri}
+                </p>
+              );
+            }
+            return <p key={index}>Unsupported assistant content.</p>;
+          })}
+        </article>
+      ))}
+      {error ? <p role="alert">{error.message}</p> : null}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          const message = draft.trim();
+          if (!message) return;
+          setDraft("");
+          settle(client.sendMessage(message));
+        }}
+      >
+        <input
+          aria-label="Message"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+        />
+        {busy ? (
+          <button type="button" onClick={() => client.abort()}>Stop</button>
+        ) : (
+          <button type="submit">Send</button>
+        )}
+      </form>
+    </section>
+  );
+}
+```
+
+`principalKey` is a browser-local identity for the authenticated user/tenant and is never sent to Noodle. Change it whenever that principal changes; the hook then aborts and clears the previous session and transcript. The hook does not register `<noodle-assistant>` or render Noodle markup.
+
+The sample fails closed on input requests until you replace that branch with a form generated from `requestedSchema`. A custom renderer must show the complete confirmation review and both decisions, handle every part it supports, and surface an explicit unsupported state for the rest. For `data-view`, map `resourceUri` or `tool` plus the bounded/redacted `result` to a component already trusted by the application. Never inject `part.data.html`, assign it to `srcdoc`, or fetch a `ui://` URI; the managed element alone supplies Noodle’s sandbox host. Do not wrap this client in another chat transport or invent user messages for interaction continuations.
+
+Outside React, use the same DOM-free client directly. It keeps the session token in memory, exposes a React-free `UIMessage` transcript with typed parts, and never registers a custom element:
 
 ```ts
 import { createAssistantClient } from "@noodleseed/assistant/client";
@@ -266,30 +384,39 @@ assistant.updateModelContext({
   structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },
 });
 
-let pendingId: string | undefined;
-let requestedSchema: unknown;
-assistant.subscribe((event) => {
-  renderAssistantEvent(event);
-  if (event.event === 'view_available') {
-    renderRegisteredView(event.data.resourceUri, event.data.result);
-  }
-  if ((event.event === 'tool_proposed' || event.event === 'input_requested') && typeof event.data.id === 'string') {
-    pendingId = event.data.id;
-    requestedSchema = event.event === 'input_requested' ? event.data.requestedSchema : undefined;
+let pending: { id: string; requestedSchema?: Readonly<Record<string, unknown>> } | undefined;
+assistant.subscribeChat((state) => {
+  renderUIMessageState(state);
+  pending = undefined;
+  for (const message of state.messages) {
+    for (const part of message.parts) {
+      if (part.type === 'data-confirmation' && part.data.status === 'pending') {
+        pending = { id: part.data.id };
+      }
+      if (part.type === 'data-input-request' && part.data.status === 'pending') {
+        pending = { id: part.data.id, requestedSchema: part.data.requestedSchema };
+      }
+      if (part.type === 'data-view') {
+        renderRegisteredView(part.data.resourceUri, part.data.result);
+      }
+    }
   }
 });
 
 await assistant.sendMessage("Book next Thursday and Friday off");
-if (pendingId) {
+if (pending) {
+  const requestedSchema = pending.requestedSchema;
   const resolution = requestedSchema
     ? { action: 'accept' as const, content: await renderPortableForm(requestedSchema) }
     : { action: 'accept' as const };
-  await assistant.respond(pendingId, resolution);
+  await assistant.respond(pending.id, resolution);
 }
 // The same pending id also accepts { action: 'decline' } or { action: 'cancel' }.
 ```
 
-`view_available` means a completed tool has a linked MCP App view. It carries the call/interaction id, tool, `ui://` identity, optional title, bounded/redacted public result, and—on current services—the self-contained bridged document. The standard element is an MCP Apps host and mounts that document behind a double iframe. It supports lifecycle, app tool/resource calls, ui/message, ui/update-model-context, links, resize, and inline/fullscreen; sampling, tasks, downloads, and remote DOM are not advertised. It also dispatches `assistant-view-available` for a customer-owned renderer.
+`subscribeChat` immediately emits a detached `{ messages, status, error? }` snapshot and then emits as `UIMessage.parts` change. Text uses `text`; Noodle confirmations, input requests, tool results, and linked views use `data-confirmation`, `data-input-request`, `data-tool-result`, and `data-view`. Interaction data moves through pending/submitting/accepted/declined/cancelled. Use raw `subscribe(...)` only for transport/session lifecycle events that are not transcript content.
+
+`data-view` means a completed tool has a linked MCP App view. It carries the call/interaction id, tool, `ui://` identity, optional title, bounded/redacted public result, and—on current services—the self-contained bridged document. The standard element is an MCP Apps host and mounts that document behind a double iframe; a customer renderer ignores it and maps the identity/result to an application-trusted component. The standard element supports lifecycle, app tool/resource calls, ui/message, ui/update-model-context, links, resize, and inline/fullscreen; sampling, tasks, downloads, and remote DOM are not advertised. It also dispatches `assistant-view-available` for a customer-owned renderer.
 
 `clientContext` and typed `pageContext` are recomputed for each turn. `updateContext(...)` remains the legacy session-exchange context; `updatePageContext(...)` replaces the fresh per-turn application hint. `updateModelContext({ content, structuredContent })` publishes one cohesive renderer snapshot for later message turns without starting a turn; every call replaces the prior snapshot rather than merging fields. These are untrusted data, not conversation history or authorization input, and the boundaries reject credential-shaped or unbounded updates. A message may re-exchange once after a pre-execution `401`; the client never auto-retries interaction decisions. `tool_proposed.arguments` is a complete schema-aware review projection and, for connector-backed tools, names the sole exact connector version/operation/resolved arguments. Sensitive/write-only fields are redacted; truncating or omitting any non-sensitive action field fails closed. Accept is bound to the server-held action and claims at most one execution attempt—clients cannot replace it. Normal terminal outcomes scrub private arguments and continuations immediately; only an accepted action still executing retains them for the one-hour unknown-outcome recovery window, after which it records `interaction_outcome_unknown` and scrubs. Without downstream idempotency this is not an exactly-once business-effect guarantee. To reconcile a lost response, explicitly repeat the same id and decision: the service returns its durable stored outcome without re-execution.
 
@@ -297,7 +424,7 @@ if (pendingId) {
 
 - Node.js 20+ for `@noodleseed/assistant/server`.
 - The package ships ESM and CommonJS with full export conditions; no bundler aliases, `transpilePackages`, or ambient type shims are needed. If resolution fails, the installed package version is outdated: update `@noodleseed/assistant` instead of adding workarounds.
-- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/client`, `/react`, and `/server` subpaths.
+- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/client`, `/react`, `/react/client`, and `/server` subpaths.
 
 ## Verify the boundary
 

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: reporting-noodle-feedback
+description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
+---
+
+<!-- noodle-skill version:0.41.0 hash:1e23938b39956ef8 -->
+
+# reporting-noodle-feedback
+
+Offer one sanitized feedback command and submit it only after informed explicit approval.
+
+## Use when
+
+- Report a Noodle Seed bug or documentation gap.
+- Propose a concrete Noodle product improvement.
+
+## Do not use when
+
+- Do not use for generic project bugs.
+- Do not send customer code, identifiers, logs, or secrets.
+
+## Required inputs
+
+- One distinct finding.
+- Sanitized observed and expected behavior.
+- User approval for the exact command.
+
+## Workflow
+
+Read and follow the canonical playbook `references/feedback.md` at `../noodle-seed/references/feedback.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+
+## Verification evidence
+
+The user saw the exact sanitized command; only a returned reference proves submission.
+
+## Recovery paths
+
+If login or rate limits block submission, report that nothing was sent and do not retry-loop.
+
+## Stop conditions
+
+Stop before running the command until the user explicitly approves it.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: verifying-mcp-delivery
+description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
+---
+
+<!-- noodle-skill version:0.41.0 hash:6ef6ef551e26b78e -->
+
+# verifying-mcp-delivery
+
+Report the highest evidence level actually rerun without upgrading weaker proof.
+
+## Use when
+
+- Verify this MCP delivery before handoff.
+- Prove which delivery layers currently pass.
+
+## Do not use when
+
+- Do not use as a substitute for fixing a known failure.
+- Do not infer hosted health from local success.
+
+## Required inputs
+
+- Requested evidence level.
+- Current target.
+- Existing evidence and its freshness.
+
+## Workflow
+
+Read and follow the canonical playbook `references/verify-and-recover.md` at `../noodle-seed/references/verify-and-recover.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/test-in-hosts.md` at `../noodle-seed/references/test-in-hosts.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+Every dependency below the requested level passes now, or the first unproven layer is explicit.
+
+## Recovery paths
+
+Hand a concrete failing layer to debugging-mcp-delivery with all passing evidence preserved.
+
+## Stop conditions
+
+Stop after the requested level passes or the first bounded failure is isolated.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: noodle-seed
-description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
+description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.39.0 hash:75dd0f6f85b04858 -->
+<!-- noodle-skill version:0.41.0 hash:2ea7d6dcc8358b35 -->
 
 # Noodle Seed
 
@@ -17,23 +17,25 @@ If the request is unrelated to the Noodle MCP surface, stop here: follow the pro
 
 ## Route the request
 
-Choose exactly one primary route from the user outcome below. Read that primary reference in full, then begin the work. Read supporting references only when the primary workflow sends you there or the named evidence exposes that concern. Stop discovery once the route is selected.
+Choose exactly one primary route from the user outcome below, then load the selected sibling skill and hand off the request. Read that primary reference in full; read supporting references only when the sibling or observed evidence requires them. Do not reread the corpus or restart discovery after the handoff.
 
-Apply this precedence when wording overlaps: diagnosis of an existing failure takes the verification route; an MCP App/UI outcome takes the App route; external API integration from credentials, a URL, or an API specification takes precedence over generic server building; hosted inspection is the read-only route; hosted mutation requires the explicitly requested deployment route.
+Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an MCP App/UI outcome takes the App route; external API integration from credentials, a URL, or an API specification takes precedence over generic server building; hosted inspection is debugging read-only; hosted mutation requires the explicitly requested deployment route.
 
 Negative routing examples: “Inspect hosted logs/status” → `inspect-hosted` (read-only). “Prepare for deployment” → the applicable build or verification route and stop with a handoff; preparation does not authorize `link`, hosted config, deployment, rollback, host writes, or submission. “Keep this local” → a build or verification route, never a hosted route.
 
-| User outcome | Primary reference | Supporting references only when needed | Done when |
+| User outcome | Load sibling skill | Canonical playbook | Done when |
 | :--- | :--- | :--- | :--- |
-| Create or extend a headless MCP server whose external API contract is already modeled | `references/build-an-mcp-server.md` | `references/authoring-workflow.md`, `references/sdk-surface.md` | The requested server behavior is locally validated and tested; connector reads have real-output evidence. |
-| Connect a real API when credentials or an API specification are available | `references/connect-an-api.md` | `references/authoring-workflow.md` | A representative live read returns populated, intentionally mapped fields without exposing credentials. |
-| Build or change an MCP App, widget, or host-visible UI | `references/build-an-mcp-app.md` | `references/experience-design.md`, `references/widgets-and-apps.md` | The UI has a stated user benefit, passes the requested checks, and degrades to useful text. |
-| Validate, test, diagnose, or recover a failing local or hosted project | `references/verify-and-recover.md` | `references/agent-contract.md`, `references/compile-errors.md` | The failing evidence layer is repaired and rerun, or the remaining blocker and exact next action are reported. |
-| Inspect or diagnose hosted status, logs, metrics, events, or deployment metadata read-only | `references/inspect-hosted.md` | None | The requested hosted evidence is reported without changing target, configuration, access, or deployment state. |
-| Deploy, configure, connect with writes, change access, or roll back a hosted MCP service when explicitly requested | `references/deploy-and-ops.md` | `references/cli-commands.md` | The requested hosted state is evidenced without claiming unperformed host or production checks. |
-| Embed a Noodle assistant in an existing SaaS or web application | `references/embedded-assistant.md` | `references/authoring-workflow.md` | The requested embed boundary works with verified identity and credential separation at the tested level. |
-| Prepare or submit an integration to a host directory | `references/publishing.md` | `references/app-directory-compliance.md` | The requested submission evidence is complete and any host-review uncertainty is explicit. |
-| Report a Noodle Seed bug, documentation gap, or product improvement | `references/feedback.md` | None | A sanitized command is shown to the user and is submitted only after explicit approval. |
+| Turn a vague MCP product idea into a bounded design before implementation | `designing-mcp-products` | `references/experience-design.md` (`references/authoring-workflow.md`) | The product contract identifies the user benefit, model boundary, evidence, and next implementation skill. |
+| Create or extend a headless MCP server whose external API contract is already modeled | `authoring-mcp-servers` | `references/build-an-mcp-server.md` (`references/authoring-workflow.md`, `references/sdk-surface.md`) | The requested server behavior is locally validated and tested; connector reads have real-output evidence. |
+| Connect a real API when credentials or an API specification are available | `connecting-apis-to-mcp` | `references/connect-an-api.md` (`references/authoring-workflow.md`) | A representative live read returns populated, intentionally mapped fields without exposing credentials. |
+| Build or change an MCP App, widget, or host-visible UI | `building-mcp-apps` | `references/build-an-mcp-app.md` (`references/experience-design.md`, `references/widgets-and-apps.md`) | The UI has a stated user benefit, passes the requested checks, and degrades to useful text. |
+| Validate, test, or prove a project at a named delivery evidence level | `verifying-mcp-delivery` | `references/verify-and-recover.md` (`references/test-in-hosts.md`) | The failing evidence layer is repaired and rerun, or the remaining blocker and exact next action are reported. |
+| Diagnose or recover an existing project with concrete local or hosted failure evidence | `debugging-mcp-delivery` | `references/verify-and-recover.md` (`references/troubleshooting.md`, `references/inspect-hosted.md`) | The failing layer is repaired and rerun, or the stable blocker and exact next action are reported. |
+| Inspect or diagnose hosted status, logs, metrics, events, or deployment metadata read-only | `debugging-mcp-delivery` | `references/verify-and-recover.md` (`references/troubleshooting.md`, `references/inspect-hosted.md`) | The requested hosted evidence is reported without changing target, configuration, access, or deployment state. |
+| Deploy, configure, connect with writes, change access, or roll back a hosted MCP service when explicitly requested | `deploying-mcp-services` | `references/deploy-and-ops.md` (`references/cli-commands.md`) | The requested hosted state is evidenced without claiming unperformed host or production checks. |
+| Embed a Noodle assistant in an existing SaaS or web application | `embedding-mcp-assistants` | `references/embedded-assistant.md` (`references/authoring-workflow.md`) | The requested embed boundary works with verified identity and credential separation at the tested level. |
+| Prepare or submit an integration to a host directory | `publishing-mcp-integrations` | `references/publishing.md` (`references/app-directory-compliance.md`) | The requested submission evidence is complete and any host-review uncertainty is explicit. |
+| Report a Noodle Seed bug, documentation gap, or product improvement | `reporting-noodle-feedback` | `references/feedback.md` (None) | A sanitized command is shown to the user and is submitted only after explicit approval. |
 
 ## Common machine loop
 

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: authoring-mcp-servers
+description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
+---
+
+<!-- noodle-skill version:0.41.0 hash:0b2fd8c7e43fc69f -->
+
+# authoring-mcp-servers
+
+Deliver focused model-facing MCP behavior through the configured TypeScript entrypoint.
+
+## Use when
+
+- Build a headless MCP server.
+- Add a typed tool, resource, or prompt.
+
+## Do not use when
+
+- Do not use when the primary outcome is a widget.
+- Do not use only to diagnose or deploy existing behavior.
+
+## Required inputs
+
+- Requested user intent.
+- Expected typed result.
+- External operation contract when applicable.
+
+## Workflow
+
+Read and follow the canonical playbook `references/build-an-mcp-server.md` at `../noodle-seed/references/build-an-mcp-server.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/authoring-workflow.md` at `../noodle-seed/references/authoring-workflow.md` only when the playbook or observed evidence names that concern.
+Load `references/sdk-surface.md` at `../noodle-seed/references/sdk-surface.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+The TypeScript behavior validates and passes local smoke; connector reads also have real-output proof.
+
+## Recovery paths
+
+Resume at the first failing compile, smoke, credential, mapping, or live-read layer.
+
+## Stop conditions
+
+Stop at local delivery unless another requested outcome explicitly authorizes a handoff.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/building-mcp-apps/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: building-mcp-apps
+description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
+---
+
+<!-- noodle-skill version:0.41.0 hash:f7fa54992c8d7692 -->
+
+# building-mcp-apps
+
+Deliver an MCP App whose visual interaction earns its place and preserves useful model-visible fallback.
+
+## Use when
+
+- Build an MCP App or widget.
+- Add a host-visible interactive workflow.
+
+## Do not use when
+
+- Do not use when concise text fully serves the user.
+- Do not use for headless server work with no UI outcome.
+
+## Required inputs
+
+- Target user and explicit UI benefit.
+- Primary interaction and states.
+- Model-visible result and text fallback.
+
+## Workflow
+
+Read and follow the canonical playbook `references/build-an-mcp-app.md` at `../noodle-seed/references/build-an-mcp-app.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/experience-design.md` at `../noodle-seed/references/experience-design.md` only when the playbook or observed evidence names that concern.
+Load `references/widgets-and-apps.md` at `../noodle-seed/references/widgets-and-apps.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+The App passes validation, local smoke, app checks, and the requested preview or host evidence level.
+
+## Recovery paths
+
+Distinguish data-contract, widget-runtime, rendering, host, and deployment failures.
+
+## Stop conditions
+
+Stop before deployment or publication unless that distinct outcome was requested.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: connecting-apis-to-mcp
+description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
+---
+
+<!-- noodle-skill version:0.41.0 hash:1e86b8704f407bd3 -->
+
+# connecting-apis-to-mcp
+
+Connect a real API using managed credentials and mappings proven against observed output.
+
+## Use when
+
+- Connect this OpenAPI URL to MCP.
+- Use these API credentials for a real connector.
+
+## Do not use when
+
+- Do not use for static local behavior.
+- Do not use when credentials or a representative safe read are unavailable.
+
+## Required inputs
+
+- API base URL and authentication scheme.
+- Representative safe read.
+- User intent and observed response shape.
+
+## Workflow
+
+Read and follow the canonical playbook `references/connect-an-api.md` at `../noodle-seed/references/connect-an-api.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/authoring-workflow.md` at `../noodle-seed/references/authoring-workflow.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+A safe live read returns populated intentionally mapped fields through the effective local target.
+
+## Recovery paths
+
+Separate authentication, transport, response-shape, mapping, and empty-result failures before editing.
+
+## Stop conditions
+
+Stop before live writes without explicit approval, known effect, and a safe target.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: debugging-mcp-delivery
+description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
+---
+
+<!-- noodle-skill version:0.41.0 hash:aa715bae12041d7c -->
+
+# debugging-mcp-delivery
+
+Repair or isolate the first failing evidence layer while preserving everything already proven.
+
+## Use when
+
+- Diagnose this failing MCP project.
+- Inspect a hosted failure from logs or status.
+
+## Do not use when
+
+- Do not use for a greenfield build with no failure evidence.
+- Do not mutate hosted state during read-only inspection.
+
+## Required inputs
+
+- Exact failing command or symptom.
+- Current target and evidence level.
+- Most recent sanitized failure.
+
+## Workflow
+
+Read and follow the canonical playbook `references/verify-and-recover.md` at `../noodle-seed/references/verify-and-recover.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/troubleshooting.md` at `../noodle-seed/references/troubleshooting.md` only when the playbook or observed evidence names that concern.
+Load `references/inspect-hosted.md` at `../noodle-seed/references/inspect-hosted.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+The failed layer is rerun successfully, or the stable blocker and exact next action are reported.
+
+## Recovery paths
+
+After two attempts with the same signature, stop editing and preserve the repro and passing layers.
+
+## Stop conditions
+
+Stop before hosted mutation unless the user separately requests deploying-mcp-services.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: deploying-mcp-services
+description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
+---
+
+<!-- noodle-skill version:0.41.0 hash:93e735b7ffb45df1 -->
+
+# deploying-mcp-services
+
+Apply only the explicitly authorized hosted mutation to the explicit org, app, and environment.
+
+## Use when
+
+- Deploy this MCP service to an explicit environment.
+- Roll back or change hosted access.
+
+## Do not use when
+
+- Do not use for preparation, inspection, or local-only work.
+- Do not select or default a mutation target implicitly.
+
+## Required inputs
+
+- Explicit org, app, and environment.
+- Authorized mutation.
+- Pre-deploy verification evidence.
+
+## Workflow
+
+Read and follow the canonical playbook `references/deploy-and-ops.md` at `../noodle-seed/references/deploy-and-ops.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/cli-commands.md` at `../noodle-seed/references/cli-commands.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+The requested hosted state is confirmed without claiming unperformed host or production checks.
+
+## Recovery paths
+
+Preserve local evidence and isolate authentication, target, build, rollout, health, or rollback failures.
+
+## Stop conditions
+
+Stop and ask when target, authority, or effect is ambiguous.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/designing-mcp-products/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: designing-mcp-products
+description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
+---
+
+<!-- noodle-skill version:0.41.0 hash:76cce86729cffbee -->
+
+# designing-mcp-products
+
+Produce the smallest decision-ready MCP product design before code or hosted mutation.
+
+## Use when
+
+- Turn a vague product idea into an MCP product.
+- Decide whether this job needs an MCP App.
+
+## Do not use when
+
+- Do not use for an already specified implementation.
+- Do not use for generic product or UI design outside MCP.
+
+## Required inputs
+
+- Target user and job.
+- System data or action the model cannot supply.
+- Requested stopping point.
+
+## Workflow
+
+Read and follow the canonical playbook `references/experience-design.md` at `../noodle-seed/references/experience-design.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load `references/authoring-workflow.md` at `../noodle-seed/references/authoring-workflow.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+A bounded product contract states user benefit, model boundary, interaction, fallback, risks, and next implementation skill.
+
+## Recovery paths
+
+If the idea is broad, reduce it to one conversational job and one representative success path.
+
+## Stop conditions
+
+Stop before implementation when the design inputs or product fit are unresolved.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.