@noodleseed/agent-kit 0.90.0 → 0.92.0

package/skills/codex/examples/acme-discovery/README.md

@@ -35,9 +35,10 @@ access: [
 ```
 
 There is no second tool set and no second app — one `server.ts`, projected onto its front doors.
-The flagship selects `model: noodleManaged()`, so an enrolled hosted deployment needs no customer model
-endpoint, name, or key and its artifact remains provider-neutral. Sponsored beta enrollment is exact to the
-org/app/environment and fails closed outside that cohort; `openAICompatible(...)` remains the BYO alternative.
+The flagship selects `model: noodleManaged()`, so a billing-attributed hosted deployment needs no customer
+model endpoint, name, or key and its artifact remains provider-neutral. The sponsored beta is available by
+default with pooled billing-account and platform-wide daily limits; `openAICompatible(...)` remains the BYO
+alternative.
 The surface `instructions` add only the website-specific voice and goal; shared product truth stays in
 `server.instructions`. This public guidance is injected into that surface's assistant turns, never MCP
 `initialize` or another assistant surface.
@@ -152,5 +153,6 @@ noodle open
 ```
 
 This example has no connector or model secrets and does not include tokens, caller-key mechanisms, or
-`.env.noodle` values. Hosted `noodleManaged()` inference requires Noodle to enroll the exact target before
-serving; local validation and tool calls do not. All destinations, prices, and URLs are fictional.
+`.env.noodle` values. Hosted `noodleManaged()` inference is available by default to billing-attributed
+deployments and remains subject to sponsored daily limits; local validation and tool calls do not use the
+hosted model. All destinations, prices, and URLs are fictional.

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

@@ -367,6 +367,13 @@ and passes `routing: { endpoints: { customer_api: cluster.apiBaseUrl } }` to
 `createAssistantSession`. Noodle validates and privately stores that route; it is not returned to the
 browser. Do not copy the route into page context, session claims, tool input, or model instructions.
 
+The authenticated assistant surface also declares `accountTier` as a model-visible session claim. Pass it
+from the same backend-owned account record as `claims: { accountTier: account.tier }`; undeclared claims are
+dropped. This is personalization context, not authorization: the verified roles/scopes beside each tool and
+the server-owned customer route remain the enforcement boundaries. The public
+[runtime guide](https://docs.noodleseed.dev/docs/guides/product-agent-guides#use-the-guide-at-runtime)
+explains how verified session claims constrain the guide content available to the model.
+
 ```bash
 noodle variables set ASSISTANT_ORIGIN https://app.example.com --scope env
 noodle variables set ASSISTANT_MODEL_BASE_URL https://model.example.com/v1 --scope env
@@ -391,7 +398,7 @@ set the bounded surface to `glass` only when translucency is intentional.
 These TypeScript values remain the reusable developer defaults. After deployment, an environment operator
 can adjust theme, logo, launcher style, position, and the bounded color palette from the Console's
 **Assistant** tab or `noodle assistant appearance` without changing the customer's embed code. See the
-[embedded assistant guide](https://docs.noodleseed.dev/guides/embedded-assistant) for precedence and reset
+[embedded assistant guide](https://docs.noodleseed.dev/docs/guides/embedded-assistant) for precedence and reset
 behavior.
 
 Create the backend credential after deployment. The CLI writes it to a mode-0600 file and never prints the
@@ -425,8 +432,12 @@ import { NoodleAssistant } from '@noodleseed/assistant/react';
 `resolvedTheme` is the application's current `'light' | 'dark'` value. Use `theme="auto"` only when the
 browser operating-system preference is intentionally authoritative.
 
-For an entirely application-owned React renderer, use the renderer-free hook. It creates no custom element
-and returns the AI SDK transcript plus the canonical client commands:
+### Minimal fail-closed custom renderer skeleton
+
+Use the renderer-free hook only when the product has a concrete reason to own the conversation UI. This
+minimal skeleton keeps the canonical client and App host, but intentionally refuses confirmation and input
+acceptance until the application implements their complete schema-aware presentation. Start with the managed
+renderer unless the application accepts every obligation below.
 
 ```tsx
 'use client';
@@ -438,12 +449,20 @@ import { useNoodleAssistant } from '@noodleseed/assistant/react/client';
 export function CustomerAssistant({
   principalKey,
   resolvedTheme,
+  onSignInRequested,
 }: {
   principalKey: string;
   resolvedTheme: 'light' | 'dark';
+  onSignInRequested: (request: {
+    signInTicket: string;
+    expiresAt: string;
+  }) => Promise<'started' | 'cancelled'>;
 }) {
   const [draft, setDraft] = useState('');
-  const { client, messages, status, error } = useNoodleAssistant({
+  const [sessionNotice, setSessionNotice] = useState('');
+  const [turnNotice, setTurnNotice] = useState('');
+  const [pendingSignInTicket, setPendingSignInTicket] = useState<string>();
+  const { client, messages, suggestions, status, error } = useNoodleAssistant({
     sessionEndpoint: '/api/noodle-assistant/session',
     principalKey,
   });
@@ -453,6 +472,16 @@ export function CustomerAssistant({
       // The hook exposes this same structured failure through `error`.
     });
   };
+  useEffect(
+    () =>
+      client.subscribe((event) => {
+        if (event.event === 'session_expired') setSessionNotice('Session expired.');
+        if (event.event === 'session_started' || event.event === 'session_reset') {
+          setSessionNotice('');
+        }
+      }),
+    [client],
+  );
 
   return (
     <section aria-label="Assistant" aria-busy={busy}>
@@ -466,20 +495,18 @@ export function CustomerAssistant({
                 <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>
+                  <p>This custom renderer has not implemented a complete schema-aware review.</p>
                   <button
                     disabled={busy || review.status !== 'pending'}
-                    onClick={() => settle(client.respond(review.id, { action: 'accept' }))}
+                    onClick={() => settle(client.respond(review.id, { action: 'decline' }))}
                   >
-                    Confirm
+                    Don't proceed
                   </button>
                   <button
                     disabled={busy || review.status !== 'pending'}
-                    onClick={() => settle(client.respond(review.id, { action: 'decline' }))}
+                    onClick={() => settle(client.respond(review.id, { action: 'cancel' }))}
                   >
-                    Don't proceed
+                    Cancel
                   </button>
                 </section>
               );
@@ -489,21 +516,28 @@ export function CustomerAssistant({
               return (
                 <section key={request.id} aria-label="Assistant needs input">
                   <p>{request.message}</p>
-                  <p>This renderer has not implemented the requested form.</p>
+                  {/* request.requestedSchema is the sole input-form contract. */}
+                  <p>This custom renderer has not implemented the requested schema form.</p>
                   <button
                     disabled={busy || request.status !== 'pending'}
                     onClick={() => settle(client.respond(request.id, { action: 'decline' }))}
                   >
-                    Cancel request
+                    Don't proceed
+                  </button>
+                  <button
+                    disabled={busy || request.status !== 'pending'}
+                    onClick={() => settle(client.respond(request.id, { action: 'cancel' }))}
+                  >
+                    Cancel
                   </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>
+                <p key={part.data.id} role="status">
+                  A result is available, but this renderer has no trusted presentation for it.
+                </p>
               );
             }
             if (part.type === 'data-view') {
@@ -516,17 +550,67 @@ export function CustomerAssistant({
                 />
               );
             }
+            if (part.type === 'data-sign-in') {
+              const request = part.data;
+              return (
+                <section key={request.id} aria-label="Sign in required">
+                  <p>Continue with your account to use this capability.</p>
+                  <button
+                    disabled={busy || pendingSignInTicket !== undefined}
+                    onClick={() => {
+                      setPendingSignInTicket(request.signInTicket);
+                      void Promise.resolve()
+                        .then(() =>
+                          onSignInRequested({
+                            signInTicket: request.signInTicket,
+                            expiresAt: request.expiresAt,
+                          }),
+                        )
+                        .then(
+                          (result) => {
+                            if (result === 'cancelled') setPendingSignInTicket(undefined);
+                          },
+                          () => setPendingSignInTicket(undefined),
+                        );
+                    }}
+                  >
+                    Sign in
+                  </button>
+                </section>
+              );
+            }
             return <p key={index}>Unsupported assistant content.</p>;
           })}
         </article>
       ))}
-      {error ? <p role="alert">{error.message}</p> : null}
+      <p role="status" aria-live="polite">
+        {sessionNotice || turnNotice || (busy ? 'Assistant is working' : '')}
+      </p>
+      {suggestions?.prompts.length ? (
+        <nav aria-label="Suggested messages">
+          {suggestions.prompts.map((prompt) => (
+            <button
+              key={prompt}
+              type="button"
+              disabled={busy}
+              onClick={() => {
+                setTurnNotice('');
+                settle(client.sendMessage(prompt));
+              }}
+            >
+              {prompt}
+            </button>
+          ))}
+        </nav>
+      ) : null}
+      {error ? <p role="alert">The assistant could not complete that request.</p> : null}
       <form
         onSubmit={(event) => {
           event.preventDefault();
           const message = draft.trim();
           if (!message) return;
           setDraft('');
+          setTurnNotice('');
           settle(client.sendMessage(message));
         }}
       >
@@ -536,7 +620,13 @@ export function CustomerAssistant({
           onChange={(event) => setDraft(event.currentTarget.value)}
         />
         {busy ? (
-          <button type="button" onClick={() => client.abort()}>
+          <button
+            type="button"
+            onClick={() => {
+              client.abort();
+              setTurnNotice('Response stopped. This does not undo a started action.');
+            }}
+          >
             Stop
           </button>
         ) : (
@@ -549,14 +639,26 @@ export function CustomerAssistant({
 ```
 
 `principalKey` stays in the browser. Change it whenever the authenticated user or tenant changes; the hook
-then aborts and clears the prior session and transcript. The sample fails closed on input requests until its
-fallback is replaced with a form generated from `requestedSchema`. A production renderer must show the
-complete confirmation review and both decisions. For `data-view`, map `resourceUri` or `tool` and the
-bounded/redacted result to a component already trusted by this application only when intentionally replacing
-the linked App with a native UI. Otherwise use `<noodle-app-view>` or its React `NoodleAppView` adapter;
-JSON result data is not the App UI. The element's semantic lifecycle identity is the client plus `view.id`
-plus `view.resourceUri`, so parent payload/callback rerenders keep the iframe and only a different view,
-disconnect, or App teardown request retires the bridge.
+then aborts and clears the prior session and transcript. The sample does not render Confirm until the host
+implements a complete schema-aware review, and it does not accept elicitation until a portable form covers
+`requestedSchema`; use the managed renderer instead of shipping either unsupported branch. Suggestions are
+hook-owned and submit ordinary messages through `client.sendMessage`.
+
+`data-sign-in` has no status and is never passed to `client.respond`. Bind `signInTicket` to the host's
+short-lived login transaction without putting it in URLs, logs, analytics, or durable browser storage. Resolve
+the callback as `started` only after the host owns one active transaction; return `cancelled` or reject when no
+transaction started so the renderer restores the sign-in affordance. A
+mixed renderer uses separate public and authenticated clients: the public shell uses `embedId`, `serviceUrl`,
+and a visitor principal key; after login, the destination mounts a new client against the same-origin session
+endpoint under the user/tenant principal key. Never pass both source options or mutate the public client's
+source in place. `session_expired` is observational: the client owns its single safe pre-execution re-exchange.
+Never add a generic Retry button or replay an interaction decision automatically.
+
+For `data-tool-result`, do not expose technical tool names or raw JSON. Prefer the linked `data-view`;
+otherwise map a known bounded result to application-trusted UI or keep the explicit unsupported state. For
+`data-view`, use `<noodle-app-view>` or its React `NoodleAppView` adapter. The element's semantic lifecycle
+identity is the client plus `view.id` plus `view.resourceUri`, so payload/callback rerenders keep the iframe
+and only a different view, disconnect, or App teardown request retires the bridge.
 App views remain inline by default: the host advertises only inline presentation and rejects a widget's
 fullscreen request. A customer-owned renderer may opt in explicitly with `allowFullscreen` on
 `NoodleAppView` or `allow-fullscreen` on `<noodle-app-view>` only when fullscreen is part of its intended
@@ -578,6 +680,13 @@ secret allowlist; regenerate existing framework-owned environment binding types
 Devtools/model exercises to synthetic data, and obtain approval before sending real connector data to an
 external model.
 
+Read `evidence.levels` in order: static host, local contract, hosted session, production browser, then
+operations. Stop at `evidence.firstUnproven`. A static result may be `passed`, `partial`, or `failed`; even
+top-level `ready: true` means only that no static blocker was detected. It never proves the local session
+contract or a production-browser flow. Value-free diagnostics call out an MCP endpoint used as the service
+URL, an HTML redirect risk, an SSR mount risk, and a cross-origin session endpoint. The command has no live
+or browser flag; its `postDeployProbes` are next actions, not executed evidence.
+
 After deployment, use the assistant doctor to verify the embed client, exact model transport, and static
 session boundary:
 
@@ -591,21 +700,10 @@ application-specific customer route. Prove routed assistant tools by
 having the authenticated embedding backend pass the user's server-verified endpoint during session
 exchange, then invoke one representative safe read.
 
-If the application deliberately sends a first turn on mount, do not combine a persistent "sent" ref with a
-mount effect. React Strict Mode can abort that provisional request and then suppress the stable remount.
-Schedule the send after the provisional cleanup and settle its promise:
-
-```tsx
-useEffect(() => {
-  let active = true;
-  queueMicrotask(() => {
-    if (active) settle(client.sendMessage(initialMessage));
-  });
-  return () => {
-    active = false;
-  };
-}, [client, initialMessage]);
-```
+Do not send a first turn on mount by default. React effect cleanup can suppress one provisional Strict Mode
+effect, but it cannot make a remount, dependency change, or client replacement idempotent. Require an
+explicit user action unless the host owns durable one-shot state and an application idempotency key that
+makes repeated sends safe.
 
 For a chat-first custom host, raw `tool_started` supplies the direct call `id` and technical tool name. Map
 known tools to concise application copy and use a neutral fallback. Reserve a stable `role="status"` region
@@ -617,39 +715,81 @@ Use `${view.id}:${view.resourceUri}` as transport identity. Different call IDs a
 must not be deduplicated generically. If this application intentionally owns one current panel for a known
 resource, declare an application-owned slot for that resource and replace only that slot.
 
-Outside React, subscribe to the DOM-free client directly and use the isolated framework-neutral App host.
+### Framework-neutral DOM client
+
+Subscribe to the DOM-free client directly without a component wrapper and use the isolated App host.
 It exposes the same conversation as headless AI SDK `UIMessage` state, including typed confirmation, input,
-tool-result, and linked-view parts, without installing React:
+tool-result, and linked-view parts:
 
 ```html
-<noodle-app-view id="assistant-app-view"></noodle-app-view>
+<div id="assistant-app-views"></div>
 ```
 
 ```ts
 import '@noodleseed/assistant/app-view';
+import {
+  type AssistantViewAvailableDetail,
+  type NoodleAppViewElement,
+} from '@noodleseed/assistant/app-view';
 import { createAssistantClient } from '@noodleseed/assistant/client';
 
 const assistant = createAssistantClient({
   sessionEndpoint: '/api/noodle-assistant/session',
 });
-const appView = document.querySelector('#assistant-app-view');
-if (!appView) throw new Error('Missing App view host');
-appView.client = assistant;
-appView.theme = resolvedTheme;
+const appViews = document.querySelector('#assistant-app-views');
+if (!appViews) throw new Error('Missing App views host');
+const mountedViews = new Map<string, NoodleAppViewElement>();
+const readResolvedTheme = (): 'light' | 'dark' =>
+  document.documentElement.classList.contains('dark') ? 'dark' : 'light';
+let resolvedTheme: 'light' | 'dark' = readResolvedTheme();
+const syncResolvedTheme = () => {
+  resolvedTheme = readResolvedTheme();
+  for (const mountedView of mountedViews.values()) mountedView.theme = resolvedTheme;
+};
+new MutationObserver(syncResolvedTheme).observe(document.documentElement, {
+  attributes: true,
+  attributeFilter: ['class'],
+});
+const appViewFor = (view: AssistantViewAvailableDetail) => {
+  const key = `${view.id}:${view.resourceUri}`;
+  let appView = mountedViews.get(key);
+  if (!appView) {
+    appView = document.createElement('noodle-app-view') as NoodleAppViewElement;
+    appView.client = assistant;
+    mountedViews.set(key, appView);
+    appViews.append(appView);
+  }
+  appView.theme = resolvedTheme;
+  return appView;
+};
 
 assistant.subscribeChat((state) => {
-  renderUIMessageState(state);
+  renderUIMessageState(state, {
+    respond: (id, response) => assistant.respond(id, response),
+  });
+  const activeViewKeys = new Set<string>();
   for (const message of state.messages) {
     for (const part of message.parts) {
-      if (part.type === 'data-confirmation' && part.data.status === 'pending') {
-        renderConfirmation(part.data, (response) => assistant.respond(part.data.id, response));
+      if (part.type === 'data-view') {
+        const key = `${part.data.id}:${part.data.resourceUri}`;
+        activeViewKeys.add(key);
+        appViewFor(part.data).view = part.data;
       }
-      if (part.type === 'data-view') appView.view = part.data;
+    }
+  }
+  for (const [key, mountedView] of mountedViews) {
+    if (!activeViewKeys.has(key)) {
+      mountedView.remove();
+      mountedViews.delete(key);
     }
   }
 });
 ```
 
+`renderUIMessageState` is application code. It must present a complete schema-aware confirmation or input
+form and require an explicit user gesture before using `respond`; never call `respond` while scanning a
+transcript snapshot.
+
 `theme="auto"` follows the operating-system preference, not a SaaS-owned toggle. Pass the resolved
 `light`/`dark` theme to `NoodleAssistant` and `<noodle-app-view>`/`NoodleAppView`; updates reach mounted MCP Apps without a
 remount. CSS custom properties inherit through the host, and documented `--ns-assistant-*` variables remain
@@ -666,6 +806,14 @@ deployment variables, and connector arguments do not select the tenant route.
 endpoint. They are not customer API bearer tokens. The exchange endpoint verifies the platform-signed
 subject assertion and mints a short-lived token scoped to the signed-in user and route binding.
 
+## Launch and qualified-usage proof
+
+Use the [embedded assistant guide](https://docs.noodleseed.dev/docs/guides/embedded-assistant) for the complete
+pre-launch, browser-proof, qualified-usage, recovery, measurement, and operator procedure; do not copy those
+commands into this example. Keep deployed capability, production-browser proof, qualified usage, and measured
+outcome separate; raw turn volume is utilization rather than outcome. Platform-owned completion events still
+require a separate human-approved analytics and customer-data contract.
+
 ## Deploy customer-protected to Noodle Seed Cloud
 
 ```bash

package/skills/codex/examples/customer-auth/src/server.ts

@@ -173,6 +173,9 @@ export default server(
       // Production origins are exact HTTPS; http://localhost:<port> is allowed for local development.
       access: authenticatedWebsite({
         origins: [assistantOrigin, 'https://dev.noodleseed.com', 'http://localhost:3000'],
+        sessionClaims: {
+          accountTier: { exposeToModel: true },
+        },
       }),
       theme: 'auto',
       layout: { mode: 'floating', position: 'bottom-center', panelWidth: 970 },

package/skills/codex/examples/customer-auth/test/server.test.ts

@@ -19,6 +19,9 @@ describe('customer-auth example', () => {
       'https://dev.noodleseed.com',
       'http://localhost:3000',
     ]);
+    expect(manifest.server.assistant?.sessionClaims).toEqual({
+      accountTier: { exposeToModel: true },
+    });
     expect(manifest.server.branding).toMatchObject({
       name: 'Noodle Seed Assistant',
       colorScheme: 'auto',
@@ -100,5 +103,8 @@ describe('customer-auth example', () => {
         confirm: true,
       },
     });
+    expect(
+      manifest.tools.find((tool) => tool.name === 'list_org_apps')?.annotations?.readOnlyHint,
+    ).toBe(true);
   });
 });

package/skills/codex/examples/customer-auth/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+
+// Keep the flagship's own contract test executable instead of inheriting the monorepo package-only glob.
+export default defineConfig({
+  test: { include: ['test/**/*.test.ts'] },
+});

package/skills/codex/examples/food-ordering/README.md

@@ -17,7 +17,7 @@ private customer data.
 | Public entry tool | `open_ordering` returns structured fallback content and renders the React widget |
 | Product and distribution projections | `agentGuide` supplies grounded cross-capability guidance; `distribution` supplies listing, publisher, legal, image, and review facts separately from the runtime manifest |
 | App-only helper tools | `search_stores`, `load_menu`, `load_item`, `read_cart`, `sync_cart`, `prepare_checkout`; mutating widget-owned helpers use `confirm: false` (equivalent to omission) and execute directly because action hints alone never gate |
-| Durable cart state | `server(..., { state: { handles: { cart } }, use: { state } })` with caller scope and revision checks |
+| Durable cart state | `server(..., { state: { handles: { cart } }, use: { state } })` with caller scope, revision checks, and explicit ticket-bound adoption when an anonymous visitor authenticates |
 | React app runtime kit | `@noodleseed/one/react` supplies app flow, shell/nav/view, async state, form, quantity, choice, and handoff primitives |
 | Multi-step widget flow | One React shell navigates stores, menu, item customization, cart, review, and handoff views through `useAppFlow` |
 | Invocation context | `server.context` sets locale/time-zone defaults, derives an ambient service area/date, and exposes optional host-supplied coordinates to tools and the reserved `noodle_context` MCP adapter; location is an untrusted convenience hint, never an authorization signal or a substitute for explicit input |

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

@@ -326,6 +326,7 @@ export default server(
           version: 'v1',
           scope: 'caller',
           ttlSeconds: 7200,
+          claimOnAuthentication: true,
           schema: cartStateSchema,
         },
       },

package/skills/codex/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.90.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.92.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/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.90.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.92.0 hash:0ccafb222038f553 -->
 
 # publishing-mcp-integrations
 
@@ -27,8 +27,8 @@ Produce complete submission evidence with host-review uncertainty stated explici
 
 ## Workflow
 
-Read and follow the canonical playbook `references/publishing.md` at `../noodle-seed/references/publishing.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
-Load `references/app-directory-compliance.md` at `../noodle-seed/references/app-directory-compliance.md` only when the playbook or observed evidence names that concern.
+Read and follow the canonical playbook at `references/publishing.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load the supporting reference at `references/app-directory-compliance.md` only when the playbook or observed evidence names that concern.
 
 ## Verification evidence
 

package/skills/codex/publishing-mcp-integrations/references/app-directory-compliance.md

@@ -0,0 +1,59 @@
+# App directory compliance (pre-submission)
+
+Use this shared checklist against the built integration before preparing a directory submission. It
+covers evidence common to app and connector directories without assuming a particular host, review
+portal, client framework, or vendor policy.
+
+## Contents
+
+- Validation evidence
+- Capability and interaction quality
+- Safety, privacy, and data handling
+- Reliability and accessibility
+- Directory-specific delta
+
+## Validation evidence
+
+A clean local validation result proves only the checks that actually ran. Record server validation,
+behavior tests, protocol conformance, production reachability, and interactive rendering as separate
+evidence levels. Never treat metadata readiness as proof of host rendering or directory acceptance.
+
+## Capability and interaction quality
+
+1. **User value** — each exposed capability solves a concrete user job and cites built behavior rather
+   than an aspiration.
+2. **Grounded capability** — knowledge, actions, and presentation come from authoritative application
+   data or bounded operations instead of invented state.
+3. **Atomic interfaces** — every action has a focused purpose, explicit input and output schemas, honest
+   effect annotations, and useful failure output.
+4. **Helpful UI only** — every interactive surface earns its place and preserves a useful text or
+   structured fallback when rendering is unavailable.
+5. **Meaningful completion** — the user can complete the promised task within the declared boundary,
+   with any external handoff clearly identified.
+
+## Safety, privacy, and data handling
+
+- Minimize model-visible and UI-visible data; remove secrets, internal identifiers, unnecessary personal
+  data, and continuation credentials from results and logs.
+- Document authentication, authorization scopes, retention, deletion, subprocessors, and external
+  handoffs accurately in the public privacy and support material.
+- Make mutations explicit, bounded, and confirmation-aware. Never imply that a read or preparation
+  request authorizes a write.
+- For regulated or consequential workflows, show source provenance, uncertainty, cautions, and the
+  boundary between information and a professional decision.
+
+## Reliability and accessibility
+
+- Exercise representative positive, negative, empty, loading, error, and recovery cases against the
+  production-shaped endpoint.
+- Preserve keyboard access, readable contrast, responsive layout, concise status feedback, and graceful
+  degradation when an interactive surface is unsupported.
+- State latency, availability, rate-limit, and support expectations using observed evidence rather than
+  unverified claims.
+
+## Directory-specific delta
+
+After the shared checklist passes, read the selected directory’s current official documentation and add
+only its verified requirements. Keep directory-specific metadata, screenshots, test accounts, policy
+statements, and review procedures in that submission evidence—not in this shared skill reference. Mark
+unknown or untested requirements explicitly, and never reuse another directory’s checklist as a proxy.

package/skills/codex/publishing-mcp-integrations/references/publishing.md

@@ -0,0 +1,63 @@
+# Publish to app directories
+
+> Preparation is read-only unless the current user request explicitly authorizes the exact deploy, access change, host write, or submission target. A request to prepare must report missing readiness work and stop before mutation.
+
+Directory requirements evolve. Identify the requested directory first and verify its current official requirements before preparing directory-specific evidence.
+
+## Contents
+
+- Shared readiness gate
+- Distribution metadata source
+- Hosted immutable distribution
+- Directory-specific evidence
+- Submission boundary
+
+## Shared readiness gate
+
+Before any submission:
+
+Use `references/app-directory-compliance.md` as this route’s canonical shared compliance checklist.
+
+Prepare evidence for a reachable production MCP endpoint, accurate capability descriptions and schemas, useful fallback behavior, realistic positive and negative tests, data minimization, privacy disclosures, support ownership, and any interactive surface the directory will review.
+
+## Distribution metadata source
+
+When the user explicitly prepares host packaging, author the host-neutral `distribution` option in the same `server.ts`; do not add it during an ordinary build that has no distribution goal. It contains listing, publisher, support, legal, assets, and review facts that cannot be derived safely from MCP capability descriptions.
+
+Reference real packaged images with `asset(...)`, write useful alt text, and include realistic positive and negative review scenarios. Name the exact expected MCP tools in each positive scenario’s `tools` array. A negative scenario is a non-invocation case: set `shouldInvoke: false` and do not define `tools`. For each MCP App screenshot, add the separate user `prompt` that produces that exact state. Capture only the rendered MCP App response—never the enclosing website, Devtools shell, host conversation, or an unrelated product photo—and meet the selected directory’s current format, dimension, and count limits. Keep reviewer credentials, tokens, secrets, personal data, and test-account passwords out of metadata and source control; supply any authorized reviewer credential out of band.
+
+`distribution` is projected separately. It leaves the canonical App Package and Runtime Artifact unchanged, so editing listing copy cannot change deployment execution or product-skill identity. A product package still needs the separately judged `agentGuide`; do not duplicate capability schemas or workflow truth in listing metadata.
+
+The shared framework can validate metadata and resolved image bytes, run an available target adapter, and create a reproducible archive. Target-specific availability and exact flags live in `references/cli-commands.md` and the live command catalog (`noodle commands --json`); never invent an unlisted target, bundle, filename, or acceptance claim.
+
+When a directory has separate installable-plugin and remote-connector submission projections, generate each with its own exact live-catalog command. Never combine their archives or describe an operator dossier as directly portal-uploadable.
+
+Local or repository testing and public-directory submission are distinct packaging states with distinct required inputs. An export command only compiles local source and writes the requested archive. It does not deploy, register, upload, submit, review, or publish the package.
+
+When an export reports `uploadArtifacts`, treat its output archive as an outer review kit. Extract it, follow the generated instructions, and upload only the named inner artifacts to their matching fields. Never substitute the outer kit for a nested single-purpose upload.
+
+## Hosted immutable distribution
+
+Publishing a deployment-bound archive is a hosted mutation. Run it only when the current request explicitly authorizes that exact deployment and target: `noodle distributions publish <deployment-id> [server.ts] --target <target>`. The command compiles local TypeScript and requires its package snapshot to exactly match the selected deployment before it uploads anything. It uses the endpoint and package identity returned by the service; never substitute a local URL or a different deployment.
+
+Use `noodle distributions list <deployment-id>` to discover immutable versions, `noodle distributions inspect <distribution-id>` to inspect one, and `noodle distributions download <distribution-id> --output <archive.zip>` to retrieve its exact archive. Download verifies the service length and digest before an atomic local write; a failed verification must leave no output file.
+
+Lifecycle and delivery are separate mutations. Run `readiness`, `review`, `release`, `rollback`, `deprecate`, `revoke`, or `grant` only when the request explicitly authorizes that exact distribution and action. Inspect first when the active state or version is not already known.
+
+Set readiness from evidence you can verify. Record `review` only from a real human-observed host status; never infer submission, approval, or publication from a generated archive or a successful Noodle command, and never put reviewer credentials or secrets in feedback.
+
+`release --visibility private` creates or advances a stable Noodle channel without anonymous discovery; `release --visibility public` enables Noodle public delivery only. Both still require the underlying MCP deployment to use exact public access. Neither action publishes to an external directory.
+
+`grant` returns one short-lived, exact-version bearer URL. Treat the complete URL as a secret, disclose it only to the authorized reviewer, and do not paste it into source, logs, issues, or durable docs. `rollback` moves only the channel pointer to an older ready version; `deprecate` stops delivery and `revoke` is terminal.
+
+A hosted archive is still a submission candidate. Creating, listing, inspecting, downloading, releasing, or granting it does not submit it to an external directory, satisfy review, or publish a host listing.
+
+## Directory-specific evidence
+
+Read the selected directory’s current official submission documentation at review time. Record each additional requirement separately from the shared checklist, including listing fields, identity verification, test credentials, screenshots, policy declarations, review limits, and appeal or resubmission steps. Never project one directory’s requirements onto another.
+
+When a requirement cannot be verified from the selected directory’s current documentation or direct review evidence, mark it unknown instead of borrowing a rule from another host.
+
+## Submission boundary
+
+Preparation is read-only. Reverify current official requirements immediately before public submission. Deployment, access changes, directory registration, credential entry, final submission, and publication each remain separate human-operated mutations that require explicit authorization for the exact target. Report remaining evidence gaps and stop when that authority or required directory access is absent.