@noodleseed/agent-kit 0.68.0 → 0.70.0

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

@@ -1,6 +1,10 @@
 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 storesScreenshot = asset('assets/food-ordering-stores.png');
+const menuScreenshot = asset('assets/food-ordering-menu.png');
+const handoffScreenshot = asset('assets/food-ordering-handoff.png');
 
 const state = connector('noodle_state')
   .version('1.0.0')
@@ -202,6 +206,108 @@ export default server(
   {
     title: 'Food Ordering',
     version: '1.0.0',
+    agentGuide: FOOD_ORDERING_AGENT_GUIDE,
+    distribution: {
+      listing: {
+        summary: 'Build a pickup noodle order.',
+        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: storesScreenshot,
+            alt: 'Food Ordering MCP App showing nearby stores',
+            prompt: 'Help me build a noodle order for pickup.',
+          },
+          {
+            source: menuScreenshot,
+            alt: 'Food Ordering MCP App showing the Harbor Noodles menu',
+            prompt: 'Show me the Harbor Noodles menu.',
+          },
+          {
+            source: handoffScreenshot,
+            alt: 'Food Ordering MCP App reviewing a checkout handoff',
+            prompt: 'Review my spicy miso bowl order before checkout.',
+          },
+        ],
+      },
+      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,
+            tools: ['open_ordering'],
+          },
+          {
+            id: 'browse_menu',
+            prompt: 'Show me vegetarian menu options nearby.',
+            expected: 'The app shows matching stores and bounded menu choices.',
+            shouldInvoke: true,
+            tools: ['search_stores', 'load_menu'],
+          },
+          {
+            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,
+            tools: ['search_stores', 'summarize_ordering_options'],
+          },
+          {
+            id: 'plan_pickup',
+            prompt: 'Plan a pickup order for Friday.',
+            expected: 'The app collects the missing fulfilment details before planning the order.',
+            shouldInvoke: true,
+            tools: ['plan_order'],
+          },
+          {
+            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,
+            tools: ['read_cart', 'prepare_checkout'],
+          },
+          // Negative scenarios are non-invocation cases, so they never declare expected tools.
+          {
+            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' },
@@ -287,6 +393,7 @@ export default server(
       permissions: { clipboardWrite: {} },
     }),
     tool('search_stores', {
+      title: 'Search stores',
       visibility: ['app'],
       description: 'Filter synthetic restaurants for the ordering widget.',
       annotations: readOnly,
@@ -298,6 +405,7 @@ export default server(
       fulfil: () => ({ stores }),
     }),
     tool('load_menu', {
+      title: 'Load store menu',
       visibility: ['app'],
       description: 'Load synthetic menu categories and items for one store.',
       annotations: readOnly,
@@ -310,6 +418,7 @@ export default server(
       fulfil: ({ input }) => ({ storeId: input.storeId, stores, items: menu }),
     }),
     tool('load_item', {
+      title: 'Load menu item',
       visibility: ['app'],
       description: 'Load item details and modifier options for the ordering widget.',
       annotations: readOnly,
@@ -318,6 +427,7 @@ export default server(
       fulfil: ({ input }) => ({ itemId: input.itemId, items: menu }),
     }),
     tool('read_cart', {
+      title: 'Read ordering cart',
       visibility: ['app'],
       description: 'Read the caller-scoped ordering cart state.',
       annotations: readOnly,
@@ -333,6 +443,7 @@ export default server(
       },
     }),
     tool('sync_cart', {
+      title: 'Update ordering cart',
       visibility: ['app'],
       description: 'Patch the caller-scoped ordering cart with the widget cart mirror.',
       annotations: action,
@@ -353,6 +464,7 @@ export default server(
       },
     }),
     tool('prepare_checkout', {
+      title: 'Prepare checkout handoff',
       visibility: ['app'],
       description: 'Prepare the caller-scoped cart for checkout handoff.',
       annotations: action,

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?: {
@@ -23,6 +24,7 @@ describe('food-ordering example', () => {
       connectors?: Record<string, { id: string; version: string }>;
       tools: Array<{
         name: string;
+        title?: string;
         visibility?: string[];
         annotations?: Record<string, unknown>;
         output?: unknown;
@@ -36,6 +38,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: {
@@ -100,5 +104,49 @@ describe('food-ordering example', () => {
       },
     });
     expect(manifest.widgets?.map((widget) => widget.name)).toContain('capabilities_card');
+    expect(manifest.tools.every((tool) => typeof tool.title === 'string')).toBe(true);
+  });
+
+  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.objectContaining({
+            alt: 'Food Ordering MCP App showing nearby stores',
+            prompt: 'Help me build a noodle order for pickup.',
+          }),
+          expect.objectContaining({
+            alt: 'Food Ordering MCP App showing the Harbor Noodles menu',
+            prompt: 'Show me the Harbor Noodles menu.',
+          }),
+          expect.objectContaining({
+            alt: 'Food Ordering MCP App reviewing a checkout handoff',
+            prompt: 'Review my spicy miso bowl order before checkout.',
+          }),
+        ],
+      },
+    });
+    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',
+    ]);
+    expect(
+      scenarios
+        .filter(({ shouldInvoke }) => !shouldInvoke)
+        .every((scenario) => !('tools' in scenario)),
+    ).toBe(true);
   });
 });

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.70.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.70.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

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