@noodleseed/agent-kit 0.68.0 → 0.69.0

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

@@ -3,7 +3,7 @@
 **Owns:** The flagship consumer ordering MCP App example: React view authoring, app-only helper tools,
 caller-scoped cart state handles, invocation context, model-visible widget state/lifecycle, packaged image
 assets, portable structured elicitation, checkout handoff policy, host actions, CSP/permissions metadata,
-and widget preview coverage.
+product-agent guidance, host-neutral distribution metadata, and widget preview coverage.
 
 Food Ordering is a generic, synthetic version of a live marketplace ordering app. It lets a user search
 stores, browse menus, customize an item, build a multi-line cart, review the order, and hand off checkout to
@@ -15,6 +15,7 @@ private customer data.
 | Capability | Example |
 | :--- | :--- |
 | 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 |
 | React app runtime kit | `@noodleseed/one/react` supplies app flow, shell/nav/view, async state, form, quantity, choice, and handoff primitives |
@@ -47,6 +48,11 @@ noodle test
 noodle dev
 ```
 
+The same `server.ts` declares `distribution` metadata for host adapters. It references real packaged images
+and keeps listing copy, support/legal URLs, and positive/negative review scenarios outside the canonical App
+Package and Runtime Artifact. The OpenAI adapter can now project those facts and the generated product skill
+into separate local-testing or public-submission archives. A Claude package remains a separate adapter.
+
 In another terminal:
 
 ```sh
@@ -71,6 +77,34 @@ For Apps metadata conformance, start `noodle dev`, copy the loopback MCP endpoin
 npx @mcpjam/cli@latest apps conformance --url http://127.0.0.1:<port>/o/demo/food-ordering/mcp --quiet --format json
 ```
 
+## Export an OpenAI plugin
+
+This flagship includes the guided workflows, listing metadata, review cases, and image assets needed to test
+OpenAI export. See the public [product-agent guide](https://docs.noodleseed.dev/docs/guides/product-agent-guides#export-an-openai-package)
+for the current package workflow and boundaries.
+
+Against its deployed MCP URL, generate the Food Ordering submission candidate with:
+
+```sh
+noodle export plugin openai \
+  --state submission \
+  --mcp-url https://food-ordering.noodleseed.app/mcp \
+  --category "Food & Drink" \
+  --output food-ordering-openai.zip
+```
+
+After registering that same URL in ChatGPT developer mode, substitute its real technical ID to generate the
+Food Ordering local test package:
+
+```sh
+noodle export plugin openai \
+  --state local \
+  --mcp-url https://food-ordering.noodleseed.app/mcp \
+  --category "Food & Drink" \
+  --registered-app-id plugin_asdk_app_0123456789abcdef0123456789abcdef \
+  --output food-ordering-openai-local.zip
+```
+
 ## Client Setup
 
 Use the CLI to print the exact setup flow for your MCP client:
@@ -106,6 +140,8 @@ Image sources:
   [`photo-1510431198580-7727c9fa1e3a`](https://images.unsplash.com/photo-1510431198580-7727c9fa1e3a), downloaded from Unsplash.
 - `assets/mint-lemonade.jpg` — Unsplash photo
   [`X7Nx327NtuA`](https://unsplash.com/photos/X7Nx327NtuA) by Imad 786.
+- `assets/lentil-soup-openai.png` and `assets/mint-lemonade-openai.png` — PNG screenshot renditions
+  produced from the two corresponding Unsplash references for OpenAI plugin packaging.
 
 Unsplash photos are free to use under the [Unsplash License](https://unsplash.com/license); attribution is
 not required, but source notes are kept here for provenance.

package/skills/codex/examples/food-ordering/src/agent-guide.ts

@@ -0,0 +1,48 @@
+import type { AgentGuideSource } from '@noodleseed/one';
+
+/** Product guidance for the model-visible ordering and planning workflows. */
+export const FOOD_ORDERING_AGENT_GUIDE = {
+  description:
+    'Use Food Ordering to browse synthetic local options, build a reviewable cart, and hand checkout to the user.',
+  useWhen: [
+    'The user wants to browse nearby food or assemble an order.',
+    'The user wants a structured pickup or delivery plan before ordering.',
+  ],
+  workflows: [
+    {
+      id: 'build_order',
+      title: 'Browse and build an order',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'open_ordering' },
+          guidance:
+            'Open the ordering app so the user can choose a store, review the cart, and control checkout handoff.',
+        },
+      ],
+    },
+    {
+      id: 'summarize_options',
+      title: 'Summarize available options',
+      steps: [{ capability: { kind: 'tool', name: 'summarize_ordering_options' } }],
+    },
+    {
+      id: 'plan_fulfilment',
+      title: 'Plan pickup or delivery',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'plan_order' },
+          guidance: 'Collect the user’s fulfilment preference without claiming to place an order.',
+        },
+      ],
+    },
+  ],
+  boundaries: [
+    'Treat every store, menu item, price, and service area in this example as synthetic.',
+    'Never claim checkout or payment completed; the final order happens only after the external handoff.',
+  ],
+  examples: [
+    { prompt: 'Help me put together a noodle order.', workflow: 'build_order' },
+    { prompt: 'What food options are available?', workflow: 'summarize_options' },
+    { prompt: 'Plan a delivery for Friday.', workflow: 'plan_fulfilment' },
+  ],
+} as const satisfies AgentGuideSource;

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

@@ -1,6 +1,9 @@
 import { annotations, asset, connector, resource, server, tool, z } from '@noodleseed/one';
+import { FOOD_ORDERING_AGENT_GUIDE } from './agent-guide.js';
 
 const heroImage = asset('assets/noodle-bowl.jpg');
+const menuScreenshot = asset('assets/lentil-soup-openai.png');
+const cartScreenshot = asset('assets/mint-lemonade-openai.png');
 
 const state = connector('noodle_state')
   .version('1.0.0')
@@ -202,6 +205,89 @@ export default server(
   {
     title: 'Food Ordering',
     version: '1.0.0',
+    agentGuide: FOOD_ORDERING_AGENT_GUIDE,
+    distribution: {
+      listing: {
+        summary: 'Browse local food, build a cart, and review checkout in conversation.',
+        description:
+          'Food Ordering is a synthetic MCP App that demonstrates store discovery, menu browsing, a caller-scoped cart, fulfilment planning, and explicit checkout handoff.',
+        keywords: ['food', 'ordering', 'delivery'],
+      },
+      publisher: {
+        name: 'Noodle Seed Examples',
+        websiteUrl: 'https://noodleseed.com',
+      },
+      support: {
+        documentationUrl: 'https://docs.noodleseed.com/examples/food-ordering',
+        supportUrl: 'https://noodleseed.com/support',
+      },
+      legal: {
+        privacyPolicyUrl: 'https://noodleseed.com/privacy',
+        termsOfServiceUrl: 'https://noodleseed.com/terms',
+      },
+      assets: {
+        icon: { source: heroImage, alt: 'Food Ordering noodle bowl' },
+        screenshots: [
+          { source: menuScreenshot, alt: 'A featured lentil soup menu item' },
+          { source: cartScreenshot, alt: 'A mint lemonade shown with the order' },
+        ],
+      },
+      review: {
+        instructions:
+          'Use the synthetic menu and guest cart. No account or reviewer credential is required.',
+        scenarios: [
+          {
+            id: 'build_order',
+            prompt: 'Help me build a noodle order for pickup.',
+            expected:
+              'The ordering app opens with stores and menu items; checkout remains a handoff.',
+            shouldInvoke: true,
+          },
+          {
+            id: 'browse_menu',
+            prompt: 'Show me vegetarian menu options nearby.',
+            expected: 'The app shows matching stores and bounded menu choices.',
+            shouldInvoke: true,
+          },
+          {
+            id: 'compare_options',
+            prompt: 'Compare the quickest open food options for me.',
+            expected: 'The app grounds its comparison in the synthetic store data.',
+            shouldInvoke: true,
+          },
+          {
+            id: 'plan_pickup',
+            prompt: 'Plan a pickup order for Friday.',
+            expected: 'The app collects the missing fulfilment details before planning the order.',
+            shouldInvoke: true,
+          },
+          {
+            id: 'review_checkout',
+            prompt: 'Review my cart before I continue to checkout.',
+            expected: 'The app shows the cart and keeps payment on the explicit external handoff.',
+            shouldInvoke: true,
+          },
+          {
+            id: 'unrelated_weather',
+            prompt: 'Will it rain tomorrow?',
+            expected: 'Food Ordering is not invoked.',
+            shouldInvoke: false,
+          },
+          {
+            id: 'unrelated_email',
+            prompt: 'Draft an email to my manager.',
+            expected: 'Food Ordering is not invoked.',
+            shouldInvoke: false,
+          },
+          {
+            id: 'unrelated_travel',
+            prompt: 'Book me a flight to Lisbon.',
+            expected: 'Food Ordering is not invoked.',
+            shouldInvoke: false,
+          },
+        ],
+      },
+    },
     use: { state },
     context: {
       defaults: { locale: 'en-US', timeZone: 'America/New_York' },

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

@@ -10,6 +10,7 @@ describe('food-ordering example', () => {
     const manifest = (await app.toManifest()) as {
       server: {
         name: string;
+        agentGuide?: unknown;
         context?: {
           defaults?: { locale?: string; timeZone?: string };
           ambient?: {
@@ -36,6 +37,8 @@ describe('food-ordering example', () => {
     };
 
     expect(manifest.server.name).toBe('food_ordering');
+    expect(manifest.server.agentGuide).toBeDefined();
+    expect(manifest.server).not.toHaveProperty('distribution');
     expect(manifest.server.context).toMatchObject({
       defaults: { locale: 'en-US', timeZone: 'America/New_York' },
       ambient: {
@@ -101,4 +104,26 @@ describe('food-ordering example', () => {
     });
     expect(manifest.widgets?.map((widget) => widget.name)).toContain('capabilities_card');
   });
+
+  it('projects host distribution metadata separately from the runtime manifest', () => {
+    const distribution = app.toDistributionMetadata();
+    expect(distribution).toMatchObject({
+      schemaVersion: 1,
+      listing: { summary: expect.stringContaining('Browse local food') },
+      assets: { icon: { alt: 'Food Ordering noodle bowl' }, screenshots: expect.any(Array) },
+    });
+    const scenarios = distribution?.review.scenarios ?? [];
+    expect(scenarios.filter(({ shouldInvoke }) => shouldInvoke).map(({ id }) => id)).toEqual([
+      'build_order',
+      'browse_menu',
+      'compare_options',
+      'plan_pickup',
+      'review_checkout',
+    ]);
+    expect(scenarios.filter(({ shouldInvoke }) => !shouldInvoke).map(({ id }) => id)).toEqual([
+      'unrelated_weather',
+      'unrelated_email',
+      'unrelated_travel',
+    ]);
+  });
 });

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.68.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.69.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.68.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.69.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/cli-commands.md

@@ -25,7 +25,7 @@ Developer-facing `noodle` commands, grouped by area. Local authoring commands (`
 | `noodle docs` | Export docs in an LLM-readable format. |
 | `noodle connect` | Print connection setup for an agent host (Claude Code, Codex, Cursor, etc.). |
 | `noodle import` | Import an OpenAPI spec into a starter `server.ts`. |
-| `noodle export` | Compile locally and write the portable manifest JSON (no service). |
+| `noodle export` | Compile locally and write a portable manifest or target host-plugin archive (no service). |
 | `noodle validate` | Author-time compile/schema/connector check; no service (`--json`, `--fix-prompt`). |
 | `noodle check` | Check tool design (`tool_design_*`) and MCP Apps/widget readiness; no service. `--min-severity warn` shows only what needs fixing. |
 | `noodle test` | Local compile plus a loopback MCP smoke. |

package/skills/codex/references/embedded-assistant.md

@@ -84,11 +84,21 @@ At most one public surface (`public` or `mixed`) and at most one authenticated s
 
 A public surface **must** declare `capabilities`: the exact positive allowlist it may reach. It is required by the type, and it is the whole externally reachable surface — a reviewer should read it in one screenful. Anything absent stays private, and a capability added to the server later is excluded until someone lists it. `authenticatedWebsite` may also take `capabilities` to narrow the in-app surface; omitted, it projects the whole server.
 
-### Mixed surfaces: not available yet
+### Mixed surfaces: let a visitor sign in mid-conversation
 
-`publicWebsite({ signIn: true })` **throws**. Mid-conversation sign-in has no runtime: nothing offers the visitor a way to sign in, so an identity-dependent capability on such a surface would simply be refused — and accepting it would also give up the compile-time guard that plain `public` provides. The option stays declared so the vocabulary and wire shape are settled.
+Add `signIn: true` to a public surface when some capabilities need a signed-in visitor. The surface becomes `mixed`: anonymous visitors start immediately, an identity-dependent capability stays **visible** so the assistant can offer it, and reaching for it raises a sign-in prompt instead of executing.
 
-Until it ships, split the audiences: keep anonymous-safe capabilities on `publicWebsite`, and serve identity-dependent ones from `authenticatedWebsite({ origins })`, where the embedding backend proves who the visitor is. One assistant can declare both.
+```ts
+access: publicWebsite({
+  origins: ["https://www.example.com"],
+  capabilities: [answerProductQuestion, requestDemo, myOrders],
+  signIn: true,   // `myOrders` reads ${user}; visitors sign in to reach it
+}),
+```
+
+Elevation runs through the **host application own login**, never a Noodle-operated one. The widget raises `assistant-sign-in-requested` with a single-use `continuation`; the page signs the visitor in as it already does, then its backend POSTs that continuation to the session exchange **with its own client credentials**. Possession of the continuation alone elevates nothing, and the service checks the client tenant owns that conversation.
+
+The conversation is kept: same history, new token, the anonymous one dead. Do not build a second identity provider for this.
 
 A connector-backed side effect needs **two** independent declarations to be reachable from a public or mixed surface: inclusion in `capabilities` **and** `{ confirm: true }` on the operation. Signing in proves who the visitor is; it does not pre-authorize an effect, so confirmation still applies on a mixed surface. Confirmation is never authentication or business authorization — the customer backend still owns payload validation, abuse controls, and idempotency. Local or session-only widget state needs no confirmation.
 

package/skills/codex/references/product-agent-guides.md

@@ -8,7 +8,7 @@ Do not wait for the user to name `agentGuide`. During every MCP server or App bu
 
 Author a guide when any of these conditions applies:
 
-- A request for an App Package or app product skill requires one. A marketplace plugin or customer-agent distribution would also need this source, but those per-app distribution surfaces are not available in this foundation.
+- A request for an App Package or app product skill requires one. A marketplace plugin or customer-agent distribution also needs this product source in addition to separate listing metadata.
 - Multiple capabilities participate in one user workflow, especially when order or purpose matters.
 - Safe or useful operation depends on product-specific ordering, grounding, clarification, boundaries, or representative examples that capability descriptions cannot express.
 
@@ -20,7 +20,7 @@ Make the judgment from the user’s stated outcome and grounded product evidence
 
 Noodle workflow skills teach a coding agent how to build and operate Noodle projects. The generated app product skill is team-local guidance for using one product. A marketplace plugin is a separate host distribution bundle.
 
-Per-app marketplace plugin generation and customer-agent distribution are not available in this foundation. If the user asks for either, explain the boundary and stop at the local App Package and product-skill workflow. Do not claim a listing, submission bundle, hosted distribution, or customer-agent projection.
+A host-neutral distribution metadata and archive framework now exists, but per-app marketplace plugin generation is not available until a target adapter lands, and customer-agent distribution is not available. If the user asks for either, explain the boundary and stop at the proven local App Package, product-skill, and metadata work. Do not claim a target bundle, submission, hosted distribution, or customer-agent projection.
 
 ## Creation workflow
 

package/skills/codex/references/publishing.md

@@ -7,6 +7,7 @@ Directory requirements evolve. Identify the requested directory first and verify
 ## Contents
 
 - Shared readiness gate
+- Distribution metadata source
 - Directory-specific evidence
 - Submission boundary
 
@@ -18,6 +19,18 @@ Use `references/app-directory-compliance.md` as this route’s canonical shared
 
 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. 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.
+
+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.
+
 ## 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.
@@ -26,4 +39,4 @@ When a requirement cannot be verified from the selected directory’s current do
 
 ## Submission boundary
 
-Preparation is read-only. Deployment, access changes, directory registration, and final submission each require explicit authorization for the exact target. Report remaining evidence gaps and stop when that authority or required directory access is absent.
+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.

package/skills/codex/references/sdk-surface.md

@@ -65,7 +65,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 
 ## Authoring signatures
 
-- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
+- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `agentGuide`, `distribution`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
 - `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.

package/skills/codex/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.68.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.69.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/codex/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.68.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.69.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ 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.68.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.69.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications