@noodleseed/agent-kit 0.59.0 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ 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."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:ec5bfcd0d8165205 -->
+<!-- noodle-skill version:0.61.0 hash:d83543258e5ca5ff -->
 
 # Noodle Seed
 
@@ -19,15 +19,16 @@ If the request is unrelated to the Noodle MCP surface, stop here: follow the pro
 
 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: 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.
+Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take 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 | Load sibling skill | Canonical playbook | Done when |
 | :--- | :--- | :--- | :--- |
 | 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. |
+| Plan how to wrap an existing application that has no stable usable public API | `wrapping-existing-applications` | `references/wrap-existing-app.md` (`references/authoring-workflow.md`, `references/tool-design.md`) | A sanitized identity-first capability map and repository-scoped implementation plan are presented for approval before mutation. |
 | 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. |
+| Connect a real API only when all four API-evidence inputs exist: API base URL, authentication scheme, representative safe read, and observed response | `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. |
@@ -63,6 +64,7 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 - `references/tool-design.md` — intent-shaped tools, titles and annotations, bounded outputs, tool-surface budget, and context provisioning.
 - `references/embedded-assistant.md` — HTTPS origins, managed model config, deploy sequencing, session exchange, browser mounting, and credential boundaries.
 - `references/connect-an-api.md` — secure credentials, probe the live API, model the observed shape, and prove real output.
+- `references/wrap-existing-app.md` — read-only identity-first planning for an existing application with no stable usable API.
 - `references/build-an-mcp-app.md` — product-fit, output-boundary, fallback, and evidence workflow for an MCP App.
 - `references/experience-design.md` — design an app experience: funnel boundary, grounding, two users, display modes, and wireframe.
 - `references/widgets-and-apps.md` — MCP Apps, typed views, widget hooks, output shaping, and CSP.

package/skills/claude-code/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ 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.59.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.61.0 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/claude-code/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ 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.59.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.61.0 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/claude-code/connecting-apis-to-mcp/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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."
+description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.61.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 
@@ -11,13 +11,12 @@ Connect a real API using managed credentials and mappings proven against observe
 
 ## Use when
 
-- Connect this OpenAPI URL to MCP.
-- Use these API credentials for a real connector.
+- Connect this API after confirming its base URL, authentication scheme, safe read, and observed response.
 
 ## Do not use when
 
 - Do not use for static local behavior.
-- Do not use when credentials or a representative safe read are unavailable.
+- Do not use when all available API evidence is stale, inaccessible, undocumented-only, or otherwise unusable.
 
 ## Required inputs
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.61.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/claude-code/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ 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.59.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.61.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/claude-code/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ 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.59.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.61.0 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/claude-code/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.61.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/claude-code/examples/customer-auth/README.md

@@ -212,10 +212,10 @@ fulfil({ input, connectors }) {
 The broker exchanges a short-lived, platform-signed assertion at the fixed token endpoint and caches the
 result by caller, connector, scopes, and a route fingerprint. The assertion carries only the route key and
 fingerprint, never the URL. The MCP access token is never forwarded to the customer API. The exchange wire
-contract lives in [docs/spec/connectors.md](../../docs/spec/connectors.md).
+contract lives in docs/spec/connectors.md.
 
 Firebase and Microsoft remain supported managed adapters; their provider-specific contracts and tests live
-in [docs/spec/auth-and-policy.md](../../docs/spec/auth-and-policy.md) and the SharePoint flagship.
+in docs/spec/auth-and-policy.md and the SharePoint flagship.
 
 ## Supabase direct-OIDC access-token hook
 

package/skills/claude-code/examples/food-ordering/src/helpers.ts

@@ -34,4 +34,5 @@ export const {
   useUpdateModelContext,
   useViewState,
   useWidgetLifecycle,
+  useWidgetReady,
 } = generateHelpers<AppType>();

package/skills/claude-code/examples/food-ordering/src/views/ordering-flow.tsx

@@ -23,6 +23,7 @@ import {
   useUpdateModelContext,
   useViewState,
   useWidgetLifecycle,
+  useWidgetReady,
   View,
   ViewStack,
 } from '../helpers.js';
@@ -74,9 +75,10 @@ function modifierLabel(value: string): string {
 }
 
 export default function OrderingFlow() {
+  const ready = useWidgetReady();
   const { displayMode, supports, theme } = useLayout();
   const toolInfo = useToolInfo('open_ordering');
-  const isPending = Object.keys(toolInfo).length === 0;
+  const isPending = !ready || Object.keys(toolInfo).length === 0;
   const entry = isOrderingEntryResult(toolInfo.structuredContent)
     ? toolInfo.structuredContent
     : undefined;
@@ -357,6 +359,7 @@ export default function OrderingFlow() {
             </div>
             <ActionBar className="nw-actions">
               <SubmitButton
+                type="button"
                 className="nw-button nw-button-primary"
                 pending={searchStores.isPending}
                 pendingLabel="Searching..."
@@ -366,6 +369,7 @@ export default function OrderingFlow() {
                 Search stores
               </SubmitButton>
               <SubmitButton
+                type="button"
                 className="nw-button"
                 pending={readCart.isPending}
                 pendingLabel="Loading..."
@@ -427,6 +431,7 @@ export default function OrderingFlow() {
                 />
                 <ActionBar className="nw-actions">
                   <SubmitButton
+                    type="button"
                     className="nw-button nw-button-primary"
                     pending={syncCart.isPending}
                     pendingLabel="Adding..."
@@ -459,6 +464,7 @@ export default function OrderingFlow() {
             </Field>
             <ActionBar className="nw-actions">
               <SubmitButton
+                type="button"
                 className="nw-button"
                 pending={syncCart.isPending}
                 pendingLabel="Saving..."
@@ -468,6 +474,7 @@ export default function OrderingFlow() {
                 Save cart
               </SubmitButton>
               <SubmitButton
+                type="button"
                 className="nw-button nw-button-primary"
                 disabled={cart.lines.length === 0}
                 pending={prepareCheckout.isPending}
@@ -491,6 +498,7 @@ export default function OrderingFlow() {
                 Edit cart
               </button>
               <SubmitButton
+                type="button"
                 className="nw-button nw-button-primary"
                 disabled={cart.lines.length === 0}
                 pending={prepareCheckout.isPending}

package/skills/claude-code/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.61.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/claude-code/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.61.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/claude-code/references/examples.md

@@ -27,7 +27,6 @@ Paths are relative to this skill directory. Assets (images/fonts) are omitted fr
 | `bitcoin` | API-key HTTP connector, custom auth header, and compute normalization. |
 | `sharepoint` | Microsoft SharePoint delegated Microsoft Entra auth and Graph tools. |
 | `internal-ops-demo` | Governed internal connectivity — tools/resources/prompts, role-shaped output. |
-| `docs-assistant` | Docs/knowledge assistant grounding coding agents in the live docs export. |
 
 ## Canonical server.ts
 

package/skills/claude-code/references/widgets-and-apps.md

@@ -34,6 +34,7 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 
 | Hook | Use for |
 | :-- | :-- |
+| `useWidgetReady` | Report when the standard MCP Apps bridge has connected; keep tool-backed controls disabled (or render loading) until this returns `true`. |
 | `useToolInfo` | Read the complete invoking tool result: treat `{}` as pending, handle `isError`, validate every required `structuredContent` field and identifier, reject malformed success data, and render dependent actions only after validation succeeds. |
 | `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `tool` helper. |
 | `useViewState` | Persist per-widget UI state across re-renders and restores: `const [value, setValue] = useViewState("key", initial)`. |
@@ -47,7 +48,7 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 | `useAppFlow` | Manage named widget views with persisted params and back-stack state: `const flow = useAppFlow({ initialView, views })`. |
 | `useHandoff` | Open server-created HTTP(S) handoff URLs through the host with status/error state; domain policy still comes from `handoff.allowedDomains`. |
 
-Bind interactive elements to tools (`useCallTool("place_order")`), drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and publish one compact, safe, cohesive snapshot with `useUpdateModelContext()` when `useLayout().supports?.modelContext` is true. Every model-context or lifecycle publication replaces the prior snapshot rather than merging fields, so include everything the model should still know. Calling `useWidgetLifecycle("name")` automatically publishes `mounted`, listens for host `cancelled` and `dismissed`, and returns a publisher for author-owned `submitted` or app-specific milestones; `mounted` is not proof that the host presented pixels. Both hooks use the standard MCP Apps model-context channel, not a host-specific API. These updates affect future model context but do not start a model turn. When an explicit user submit/cancel should receive an immediate reply, also call `useSendFollowUpMessage()` from that user action. `data-llm` may remain a DOM inspection hint, but it is not the bidirectional model-state contract. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
+Bind interactive elements to tools (`useCallTool("place_order")`), keep bridge-backed controls disabled until `useWidgetReady()` is true, drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and publish one compact, safe, cohesive snapshot with `useUpdateModelContext()` when `useLayout().supports?.modelContext` is true. Generated form workflows use the portable `<Form onSubmit={...}>` component with a submit button; never add browser-navigation `action`, `method`, or `target` attributes. Existing intrinsic React forms are valid when their `onSubmit` handler calls `preventDefault()` before the explicit tool call and omits those navigation attributes. Standalone actions use an explicit `type="button"` and call the tool from their click handler. In every case the widget calls the standard MCP Apps tool bridge itself — never rely on a host to translate native form submission into a tool call, and never branch on a host name. Every model-context or lifecycle publication replaces the prior snapshot rather than merging fields, so include everything the model should still know. Calling `useWidgetLifecycle("name")` automatically publishes `mounted`, listens for host `cancelled` and `dismissed`, and returns a publisher for author-owned `submitted` or app-specific milestones; `mounted` is not proof that the host presented pixels. Both hooks use the standard MCP Apps model-context channel, not a host-specific API. These updates affect future model context but do not start a model turn. When an explicit user submit/cancel should receive an immediate reply, also call `useSendFollowUpMessage()` from that user action. `data-llm` may remain a DOM inspection hint, but it is not the bidirectional model-state contract. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Form`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`); raw markup must cancel native form navigation explicitly.
 
 ## Worked widget recipe
 
@@ -63,7 +64,7 @@ import type { ServerDefinition } from '@noodleseed/one';
 import { Action, ActionBar, AsyncBoundary, Feedback, Field, Flow, Frame, Region, Select, generateHelpers } from '@noodleseed/one/react';
 
 // One call wires the typed host bridge; destructure only the hooks this view uses.
-const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useSendFollowUpMessage, useUpdateModelContext, useWidgetLifecycle } =
+const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useSendFollowUpMessage, useUpdateModelContext, useWidgetLifecycle, useWidgetReady } =
   generateHelpers<ServerDefinition>();
 
 type OrderResult = {
@@ -85,8 +86,9 @@ function isOrderResult(value: unknown): value is OrderResult {
 }
 
 export default function OrderStatus() {
+  const ready = useWidgetReady();
   const toolInfo = useToolInfo('show_order');
-  const isPending = Object.keys(toolInfo).length === 0;
+  const isPending = !ready || Object.keys(toolInfo).length === 0;
   const shown = isOrderResult(toolInfo.structuredContent) ? toolInfo.structuredContent : undefined;
   const placeOrder = useCallTool('place_order'); // calls the widget-only helper tool
   const { supports } = useLayout();
@@ -138,7 +140,7 @@ export default function OrderStatus() {
       </Region>
       {confirmed?.status ? <Feedback status="success">{confirmed.status}</Feedback> : null}
       <ActionBar>
-      <Action variant="primary" pending={placeOrder.isPending} pendingLabel="Placing…"
+      <Action type="button" variant="primary" disabled={!ready} pending={placeOrder.isPending} pendingLabel="Placing…"
         onClick={submitOrder}
       >
         Place order

package/skills/claude-code/references/wrap-existing-app.md

@@ -0,0 +1,65 @@
+# Outcome
+
+Produce a sanitized, repository-grounded plan for wrapping an existing application with a focused Noodle Seed MCP server. Discovery is read-only: present the capability map and implementation phases in the conversation, then stop before writing a plan or source file until the user explicitly authorizes that local mutation and repository.
+
+## Contents
+
+- Use when
+- Do not use when
+- Required inputs
+- Workflow
+- Verification evidence
+- Recovery paths
+- Stop conditions
+
+## Use when
+
+- An existing web application has internal HTTP handlers, framework-owned server calls, or inline database-backed logic but no stable, usable public API or specification.
+- The user wants a decision-complete integration plan before changing the application or Noodle project.
+
+## Do not use when
+
+- Only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use the API-connection route. If any input is missing, stale, inaccessible, undocumented-only, or otherwise unusable, remain on the existing-application planning route.
+- The request is already-approved implementation, failure diagnosis, deployment, publication, or a host-visible App outcome; use that owning route.
+- Source access is unavailable and the user expects a repository-grounded plan. Return the bounded evidence checklist instead of inventing routes or schemas.
+
+## Required inputs
+
+Confirm the repository or repositories in scope, the user jobs to expose, the requested stopping point, which identity provider authenticates end users, whether callers are the owner's staff or the application's customers, and whether the relevant deployment has one static preconfigured downstream origin.
+
+Never read or print `.env` / `.env.noodle` values, credential stores, browser cookies, production records, secret-bearing logs, or customer payloads. Inspect source, route declarations, authentication middleware, tests, and non-secret configuration declarations only. Record sanitized capability descriptions and source locations, never copied customer code or data.
+
+## Workflow
+
+1. **Establish authority.** Name every repository in scope and whether the user requested discovery, a draft plan, local implementation, or a higher evidence level. Discovery alone authorizes no file or hosted mutation.
+2. **Ask identity first.** Before connector design, ask which identity provider authenticates end users and whether MCP callers are staff or customers. Separate **inbound MCP identity** from **downstream application authorization**. A supported provider can simplify inbound configuration; it does not automatically authorize downstream calls. An application session is not itself an inbound customer identity. Without a standards-based issuer, current production choices are the staff/service-credential path or a customer-built standards-based authorization server; the generic identity bridge is demand-gated and not shipped.
+3. **Choose downstream authorization honestly.** A shared service credential provides attribution, not per-user authorization, and should be least-privilege. Once Noodle has a verified caller identity, a delegated path requires one compatible token endpoint, whether existing or newly added, plus bearer acceptance in the relevant middleware. That endpoint does not solve the inbound session-only identity gap. Logic without a stable HTTP entry point may also need a thin HTTP handler over the existing business function.
+4. **Choose routing.** Use one static `http` connector with one static preconfigured downstream origin so the same server can serve embedded and external MCP clients. The canonical no-API path is a small application-owned integration layer with stable HTTPS handlers over existing business functions. Any downstream origin receiving a service or delegated credential must use HTTPS. Reject redirects for requests carrying service or delegated credentials; require the final HTTPS origin to be configured directly. If the application requires multi-origin routing or has no stable HTTP origin, stop, report a blocker, and hand off to the existing owning routing workflow. Browser input, model text, page context, tool arguments, and caller input cannot select an origin.
+5. **Map jobs, not routes.** For each user job record a sanitized source location, current HTTP/auth boundary, read or action effect, route-adapter need, proposed intent-shaped tool, minimal typed result, confirmation need, and verification evidence. Treat five to twelve tools as a normal budget, not a minimum; a smaller product should ship fewer. Design intent tools, not one tool per internal route.
+6. **Reject unstable seams.** Do not call an unstable server-call protocol whose identifier or serialization changes across builds. Never use direct database access, including ORM or SQL; it bypasses application authorization and business rules. Do not log in and copy a browser session into the runtime; copying a browser session or its credentials into the runtime is prohibited. Do not treat a service credential as per-user authorization. Propose a narrow application-owned HTTP handler instead.
+7. **Separate implementation ownership.** Produce an existing-application phase for handlers/auth/tests, a Noodle-project phase for TypeScript connector/tools/fakes/tests, and a cross-surface verification phase. If repositories differ, create separate repository-scoped plans and approval boundaries.
+8. **Present and stop.** Show the capability map, identity/routing decision, minimum honest application changes, rejected alternatives, test matrix, risks, and phases in the conversation. A design approval is review only. Local implementation requires an explicit “proceed” for the named repository. Local implementation approval does not authorize hosted configuration, live writes, deployment, publication, or issue-state changes; those require their own authority.
+9. **Hand off approved work.** Once a decision-complete local plan is explicitly authorized, persist it when repository workflow requires and hand it to `executing-noodle-plans`. Use the existing server-authoring and API-connection playbooks for implementation and real-output evidence; do not add another task loop here.
+
+## Verification evidence
+
+- **Discovery:** repository instructions, stable HTTP boundaries, auth middleware, and tests were inspected read-only without secret values or copied customer data.
+- **Decision:** inbound identity, downstream authorization, one static preconfigured downstream origin, and required application changes are explicit rather than inferred.
+- **Product:** each proposed tool maps to a user job, typed result, effect, and backing operation within the stated surface budget.
+- **Plan:** application, Noodle, and cross-surface phases name files or subsystems, tests, blockers, approval boundaries, and the first unproven layer.
+- **Conformance boundary:** a later representative safe `noodle tools call` can prove one observed mapping; it does not prove general schema conformance. A dedicated conformance feature is separate.
+
+## Recovery paths
+
+- Unknown identity provider or caller population: stop before choosing customer auth or delegated credentials and ask that one question.
+- No source access: provide the exact route/auth/test evidence checklist and report that no repository-grounded plan was produced.
+- Stable origin but no safe stable HTTP boundary: plan the smallest application-owned stable HTTPS adapter over existing business functions instead of calling a private server protocol.
+- A multi-origin requirement or no stable HTTP origin: stop, report the routing blocker, and hand off to the existing owning routing workflow; browser, model, tool, and caller input cannot select an origin.
+- Missing safe live verification input or working credential: leave that evidence explicitly unproven and name the exact prerequisite. A missing reachable service or action sandbox is handled the same way.
+
+## Stop conditions
+
+- Stop after presenting the draft capability map and plan until the user explicitly approves the next local mutation and repository.
+- Stop before live writes, hosted configuration, deployment, publication, or issue-state mutation without separate explicit authorization.
+- Stop blocked and hand off to the existing owning routing workflow only when the application requires multi-origin routing or has no stable HTTP origin.
+- This workflow does not add an importer, generate manifests or IR, or implement live schema probing, inference, or diffing.

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

@@ -3,7 +3,7 @@ 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.59.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.61.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.61.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/claude-code/wrapping-existing-applications/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: wrapping-existing-applications
+description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
+---
+
+<!-- noodle-skill version:0.61.0 hash:eccc3c158dcafba8 -->
+
+# wrapping-existing-applications
+
+Produce the smallest safe, repository-grounded existing-application integration plan before any mutation.
+
+## Use when
+
+- Plan how to wrap an existing application that has no usable public API.
+- Map internal application capabilities into an approved Noodle Seed implementation plan.
+
+## Do not use when
+
+- Do not use when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response; use `connecting-apis-to-mcp`. Missing, stale, inaccessible, undocumented-only, or otherwise unusable API evidence remains in `wrapping-existing-applications`.
+- Do not use to execute an approved plan, diagnose a concrete failure, or mutate hosted state.
+
+## Required inputs
+
+- Repository scope and requested stopping point.
+- Target user jobs.
+- End-user identity provider and caller population.
+- One static preconfigured downstream origin, or a routing blocker and owning-workflow handoff.
+
+## Workflow
+
+Read and follow the canonical playbook `references/wrap-existing-app.md` at `../noodle-seed/references/wrap-existing-app.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/tool-design.md` at `../noodle-seed/references/tool-design.md` only when the playbook or observed evidence names that concern.
+
+## Verification evidence
+
+A sanitized capability map and repository-scoped plan state identity, authorization, routing, application changes, tool budget, tests, blockers, and the first unproven layer.
+
+## Recovery paths
+
+With a stable origin but no safe stable HTTP boundary, plan the smallest application-owned stable HTTPS adapter over existing business functions. If a safe live verification input or working credential is missing, leave that evidence explicitly unproven and name the exact prerequisite. Only multi-origin routing or no stable HTTP origin blocks and hands off to the existing owning routing workflow.
+
+## Stop conditions
+
+Stop after presenting the draft plan and before any file or hosted mutation until the user explicitly authorizes the exact next action and 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/SKILL.md

@@ -3,7 +3,7 @@ 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."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:ec5bfcd0d8165205 -->
+<!-- noodle-skill version:0.61.0 hash:d83543258e5ca5ff -->
 
 # Noodle Seed
 
@@ -19,15 +19,16 @@ If the request is unrelated to the Noodle MCP surface, stop here: follow the pro
 
 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: 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.
+Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take 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 | Load sibling skill | Canonical playbook | Done when |
 | :--- | :--- | :--- | :--- |
 | 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. |
+| Plan how to wrap an existing application that has no stable usable public API | `wrapping-existing-applications` | `references/wrap-existing-app.md` (`references/authoring-workflow.md`, `references/tool-design.md`) | A sanitized identity-first capability map and repository-scoped implementation plan are presented for approval before mutation. |
 | 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. |
+| Connect a real API only when all four API-evidence inputs exist: API base URL, authentication scheme, representative safe read, and observed response | `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. |
@@ -63,6 +64,7 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 - `references/tool-design.md` — intent-shaped tools, titles and annotations, bounded outputs, tool-surface budget, and context provisioning.
 - `references/embedded-assistant.md` — HTTPS origins, managed model config, deploy sequencing, session exchange, browser mounting, and credential boundaries.
 - `references/connect-an-api.md` — secure credentials, probe the live API, model the observed shape, and prove real output.
+- `references/wrap-existing-app.md` — read-only identity-first planning for an existing application with no stable usable API.
 - `references/build-an-mcp-app.md` — product-fit, output-boundary, fallback, and evidence workflow for an MCP App.
 - `references/experience-design.md` — design an app experience: funnel boundary, grounding, two users, display modes, and wireframe.
 - `references/widgets-and-apps.md` — MCP Apps, typed views, widget hooks, output shaping, and CSP.

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

@@ -3,7 +3,7 @@ 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.59.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.61.0 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.61.0 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

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

@@ -1,9 +1,9 @@
 ---
 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."
+description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.61.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 
@@ -11,13 +11,12 @@ Connect a real API using managed credentials and mappings proven against observe
 
 ## Use when
 
-- Connect this OpenAPI URL to MCP.
-- Use these API credentials for a real connector.
+- Connect this API after confirming its base URL, authentication scheme, safe read, and observed response.
 
 ## Do not use when
 
 - Do not use for static local behavior.
-- Do not use when credentials or a representative safe read are unavailable.
+- Do not use when all available API evidence is stale, inaccessible, undocumented-only, or otherwise unusable.
 
 ## Required inputs
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.61.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.61.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

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

@@ -3,7 +3,7 @@ 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.59.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.61.0 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.59.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.61.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/codex/examples/customer-auth/README.md

@@ -212,10 +212,10 @@ fulfil({ input, connectors }) {
 The broker exchanges a short-lived, platform-signed assertion at the fixed token endpoint and caches the
 result by caller, connector, scopes, and a route fingerprint. The assertion carries only the route key and
 fingerprint, never the URL. The MCP access token is never forwarded to the customer API. The exchange wire
-contract lives in [docs/spec/connectors.md](../../docs/spec/connectors.md).
+contract lives in docs/spec/connectors.md.
 
 Firebase and Microsoft remain supported managed adapters; their provider-specific contracts and tests live
-in [docs/spec/auth-and-policy.md](../../docs/spec/auth-and-policy.md) and the SharePoint flagship.
+in docs/spec/auth-and-policy.md and the SharePoint flagship.
 
 ## Supabase direct-OIDC access-token hook
 

package/skills/codex/examples/food-ordering/src/helpers.ts

@@ -34,4 +34,5 @@ export const {
   useUpdateModelContext,
   useViewState,
   useWidgetLifecycle,
+  useWidgetReady,
 } = generateHelpers<AppType>();