@noodleseed/agent-kit 0.68.0 → 0.70.0

package/skills/claude-code/references/authoring-workflow.md

@@ -405,6 +405,26 @@ Author managed config as `secret("NAME")` / `variable("NAME")` and operate it wi
 
 To place the same server tools inside a SaaS web app, declare `assistant: embeddedAssistant(...)` alongside the one server-level brand kit. Read `embedded-assistant.md` before integrating: it owns the HTTPS-origin rule, managed model configuration, required deploy-before-client sequence, customer-backend exchange, browser mount, and verification checklist.
 
+## Knowledge components
+
+Ground an assistant in controlled documents and the customer's live public site with one declaration — never a handwritten `search`/`fetch` tool pair, a provider name, a sync job, or an index manifest. Declare `knowledge(...)` with `file(...)` documents (UTF-8 `.md`/`.txt`, project-root relative, ≤100 files, ≤1 MiB each, ≤25 MiB per component) and `site(...)` live scopes (exact HTTPS origin plus positive path globs), pass the declaration in the server's `knowledge` array, and include it in a public website surface's `capabilities` to project the generated `search_<name>` capability:
+
+```ts
+const product = knowledge('product', {
+  title: 'Product knowledge',
+  description: 'Public product, pricing, and support information.',
+  documents: [
+    file('./knowledge/product.md', { title: 'Product guide' }),
+    file('./knowledge/faq.txt', { title: 'FAQ' }),
+  ],
+  sites: [
+    site({ origin: 'https://www.acme.example', include: ['/docs/**', '/pricing'] }),
+  ],
+});
+```
+
+The compiler validates and hashes every document at build time (bad extensions, root escapes, symlinks, oversize, and non-UTF-8 fail `noodle validate` with the exact path); deployment publishes versioned files transactionally with the app and the provider keeps live-site content current. Component names are lowercase snake-case; each component implies exactly one generated bounded search capability with cited results.
+
 ## Boundaries
 
 Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env`, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/claude-code/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/claude-code/references/compile-errors.md

@@ -56,6 +56,8 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `invalid_asset` | Fix the `asset("./path")` reference; the file must exist and be a supported asset type. |
 | `invalid_capability_requirement` | Correct the declared capability/permission requirement to a supported value. |
 | `state_secret_field` | Remove the secret-shaped field from widget/handle state; secrets must never be stored in state or sent to widgets. |
+| `invalid_knowledge` | Fix the `knowledge()` declaration: documents must be existing UTF-8 `.md`/`.txt` files inside the project root (no symlinks), within the 100-file / 1 MiB / 25 MiB bounds, and sites need an exact HTTPS origin plus at least one include glob. |
+| `knowledge_unhashed` | Compile from the project root (`noodle validate`/`noodle dev`) so declared knowledge documents can be read and hashed. |
 | `unknown_connector_alias` | The tool calls a connector alias not declared in `use`/`provides`; add it or fix the alias (see `suggestions`). |
 | `connector_not_in_catalog` | The referenced connector is not in the resolved catalog; add it to the project connectors or correct the reference. |
 | `unknown_operation` | The connector has no such operation; use an operation declared on that connector (see `didYouMean`/`suggestions`). |

package/skills/claude-code/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/claude-code/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/claude-code/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,22 @@ 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. 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.
+
 ## 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 +43,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/claude-code/references/sdk-surface.md

@@ -58,14 +58,17 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `customerEndpoint`
 - `embeddedAssistant`
 - `externalExchange`
+- `file`
 - `gmailConnector`
+- `knowledge`
 - `managedSecret`
 - `openAICompatible`
 - `publicWebsite`
+- `site`
 
 ## 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/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.68.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.70.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.68.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.70.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/claude-code/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.70.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications
 

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.68.0 hash:13ddce01769caae4 -->
+<!-- noodle-skill version:0.70.0 hash:13ddce01769caae4 -->
 
 # Noodle Seed
 

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.68.0 hash:11523cb33b9473c0 -->
+<!-- noodle-skill version:0.70.0 hash:11523cb33b9473c0 -->
 
 # 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.68.0 hash:9fd67d4d24328e15 -->
+<!-- noodle-skill version:0.70.0 hash:9fd67d4d24328e15 -->
 
 # building-mcp-apps
 

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

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 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.68.0 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.70.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/creating-product-agent-guides/SKILL.md

@@ -3,7 +3,7 @@ name: creating-product-agent-guides
 description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
 ---
 
-<!-- noodle-skill version:0.68.0 hash:0fa48a82fe836cf0 -->
+<!-- noodle-skill version:0.70.0 hash:0fa48a82fe836cf0 -->
 
 # creating-product-agent-guides
 

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.68.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.70.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.68.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.70.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.68.0 hash:78a6f181b61f92f1 -->
+<!-- noodle-skill version:0.70.0 hash:78a6f181b61f92f1 -->
 
 # 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.68.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.70.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

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

@@ -28,7 +28,7 @@ There is no second tool set and no second app — one `server.ts`, projected ont
 and closed by default: a tool added to this server later is unreachable from the website until someone
 lists it. A tool that needed a signed-in user could not be listed here at all (the compiler rejects it);
 serve those from `authenticatedWebsite({ origins })` instead, where Acme's own backend proves who the
-visitor is. Mid-conversation sign-in on a public surface is not available yet.
+visitor is, or add `signIn: true` so visitors sign in mid-conversation through Acme own login.
 
 ## Design spec (write this before the code)
 

package/skills/codex/examples/acme-discovery/src/knowledge/faq.txt

@@ -0,0 +1,10 @@
+ACME GETAWAYS FAQ
+
+Q: Does the assistant book and take payment?
+A: No. The assistant shapes the trip and hands off to Acmes own checkout with a signed link.
+
+Q: How current are prices?
+A: Starting prices come from Acmes live site; the assistant cites the page it used.
+
+Q: Can I compare destinations?
+A: Yes, ask for a shortlist by vibe, month, or budget.

package/skills/codex/examples/acme-discovery/src/knowledge/product.md

@@ -0,0 +1,7 @@
+# Acme Getaways product guide
+
+Acme Getaways curates four destination types: beach, mountains, culture, and city escapes. Every listing shows a real starting price and the best months to travel. Bookings, payments, and date selection happen on Acmes own site through a signed handoff link; the assistant never takes payment details.
+
+## Cancellation and support
+
+All trips can be cancelled free within 48 hours of the handoff. Support runs seven days a week through the chat on book.acme.example.

package/skills/codex/examples/acme-discovery/src/server.ts

@@ -1,10 +1,13 @@
 import {
   annotations,
   embeddedAssistant,
+  file,
+  knowledge,
   openAICompatible,
   publicWebsite,
   secret,
   server,
+  site,
   tool,
   variable,
   z,
@@ -196,6 +199,27 @@ const shortlistGetaway = tool('shortlist_getaway', {
   }),
 });
 
+// Grounding beyond the catalog: two controlled files answer policy/pricing/support questions with
+// citations, and Acme's live public site stays current through its search provider — no sync job,
+// no handwritten search tool. One declaration, one generated `search_destinations` capability.
+const destinations = knowledge('destinations', {
+  title: 'Acme Getaways destinations',
+  description: 'Public destination, pricing, cancellation, and support information.',
+  documents: [
+    file('./knowledge/product.md', {
+      title: 'Product guide',
+      sourceUrl: 'https://getaways.acme.example/product',
+    }),
+    file('./knowledge/faq.txt', { title: 'FAQ' }),
+  ],
+  sites: [
+    site({
+      origin: 'https://getaways.acme.example',
+      include: ['/destinations/**', '/pricing', '/support'],
+    }),
+  ],
+});
+
 export default server(
   'acme_discovery',
   {
@@ -217,7 +241,8 @@ export default server(
     // The same three tools also serve Acme's own marketing site, with no second tool set and no
     // session backend: a visitor with no account gets the discovery carousel and the booking
     // handoff. `capabilities` is the whole externally reachable surface — short enough to review in
-    // one glance, and closed by default when a tool is added to the server later.
+    // one glance, and closed by default when a tool is added to the server later. The knowledge
+    // component projects its generated search capability the same way a tool does.
     assistant: embeddedAssistant({
       model: openAICompatible({
         baseUrl: variable('ASSISTANT_MODEL_BASE_URL'),
@@ -226,11 +251,12 @@ export default server(
       }),
       access: publicWebsite({
         origins: ['https://getaways.acme.example'],
-        capabilities: [discoverGetaways, createHandoff, shortlistGetaway],
+        capabilities: [destinations, discoverGetaways, createHandoff, shortlistGetaway],
       }),
       layout: { mode: 'floating', position: 'bottom-right' },
       labels: { welcomeHeading: 'Where would you like to go?' },
     }),
+    knowledge: [destinations],
   },
   [discoverGetaways, createHandoff, shortlistGetaway],
 );

package/skills/codex/examples/acme-discovery/test/server.test.ts

@@ -21,4 +21,14 @@ describe('acme-discovery example', () => {
     expect(text).toContain('create_handoff');
     expect(text).toContain('shortlist_getaway');
   });
+
+  it('declares the grounded knowledge component and its live site scope', async () => {
+    const manifest = (await app.toManifest()) as { server: { knowledge?: unknown[] } };
+    // One declaration: controlled files plus the live public site, compiled later into the
+    // generated `search_destinations` capability with citations.
+    expect(manifest.server.knowledge).toHaveLength(1);
+    const text = JSON.stringify(manifest);
+    expect(text).toContain('knowledge/product.md');
+    expect(text).toContain('https://getaways.acme.example');
+  });
 });

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. Explicit OpenAI and Claude adapters project those facts with the generated
+product skill; installable plugin archives and directory-submission dossiers remain separate outputs.
+
 In another terminal:
 
 ```sh
@@ -71,6 +77,65 @@ 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
+```
+
+Extract `food-ordering-openai.zip` before using the portal. Upload
+`submission/chatgpt-app-submission.json` to the Codex-assisted import field and
+`submission/food-ordering-skill.zip` to **With MCP → Skills**. The outer ZIP is the complete review kit and
+is not itself a valid skill upload; `submission/README.md` repeats the portal steps.
+
+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
+```
+
+## Export for Claude
+
+Claude Code plugin packaging and Anthropic Connector Directory review are separate outputs. Generate the
+installable plugin repository with:
+
+```sh
+noodle export plugin claude \
+  --mcp-url https://food-ordering.noodleseed.app/mcp \
+  --output food-ordering-claude.zip
+```
+
+Generate the credential-free operator dossier for the remote Connector Directory with:
+
+```sh
+noodle export connector claude \
+  --mcp-url https://food-ordering.noodleseed.app/mcp \
+  --auth none \
+  --category "Food & Drink" \
+  --output food-ordering-anthropic-connector.zip
+```
+
+The dossier is deliberately marked `portalUploadable: false`: it gathers the listing, tool annotations,
+use cases, allowed-link candidates, test-account guidance, and MCP App screenshot evidence, but a human must
+verify ownership/compliance and enter the final answers in Anthropic's portal. The plugin ZIP does not
+contain this dossier.
+
 ## Client Setup
 
 Use the CLI to print the exact setup flow for your MCP client:
@@ -95,17 +160,21 @@ connector secrets and does not include tokens, caller-key mechanisms, or `.env.n
 
 ## Demo Assets
 
-The packaged demo images live under `assets/` and are public web assets when deployed. The current app uses
-`assets/noodle-bowl.jpg` as the server branding image.
+The packaged demo images live under `assets/`. The current app uses `assets/noodle-bowl.jpg` as the server
+branding image. Its three distribution screenshots are real, response-only MCP App captures from Noodle
+Devtools at 2× device scale; each is 1640×970 PNG and has the producing user prompt next to its `asset(...)`
+reference in `server.ts`.
 
 Image sources:
 
 - `assets/noodle-bowl.jpg` — Unsplash photo
   [`IRv8V9Hb8gI`](https://unsplash.com/photos/IRv8V9Hb8gI), downloaded from Unsplash.
-- `assets/lentil-soup.jpg` — Unsplash image
-  [`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.
-
-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.
+- `assets/food-ordering-stores.png` — store-discovery state produced by “Help me build a noodle order for
+  pickup.”
+- `assets/food-ordering-menu.png` — Harbor Noodles menu state produced by “Show me the Harbor Noodles
+  menu.”
+- `assets/food-ordering-handoff.png` — checkout-handoff state produced by “Review my spicy miso bowl order
+  before checkout.”
+
+The Unsplash branding photo is free to use under the [Unsplash License](https://unsplash.com/license);
+attribution is not required, but the source note is 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;