@noodleseed/agent-kit 0.62.1 → 0.63.1

package/package.json

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

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:d83543258e5ca5ff -->
+<!-- noodle-skill version:0.63.1 hash:88e3ae21d02f2fe7 -->
 
 # Noodle Seed
 
@@ -56,6 +56,7 @@ Inside the installed plugin, perform mapped steps with `noodle-readiness` tools
 This is a lookup catalog, not a discovery checklist. Return here only when the selected primary route names a missing technical detail:
 
 - `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
+- `references/product-agent-guides.md` — author one host-neutral guide for a product MCP surface.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.

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

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.63.1 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

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

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.63.1 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/claude-code/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.62.1 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.63.1 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

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

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.63.1 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

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

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.63.1 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

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

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.63.1 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

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

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

package/skills/claude-code/examples/acme-tasks/src/agent-guide.ts

@@ -0,0 +1,53 @@
+import type { AgentGuideSource } from '@noodleseed/one';
+
+/** Product guidance is authored once for the full Acme Tasks MCP surface. */
+export const ACME_TASKS_AGENT_GUIDE = {
+  description: 'Use Acme Tasks to review, capture, prioritize, and complete the team task list.',
+  useWhen: [
+    'The user asks about their Acme work items.',
+    'The user wants to capture or finish an Acme task.',
+  ],
+  workflows: [
+    {
+      id: 'review_tasks',
+      title: 'Review today’s tasks',
+      intent: 'Ground the task list before taking action.',
+      steps: [
+        { capability: { kind: 'tool', name: 'list_today' } },
+        {
+          capability: { kind: 'tool', name: 'set_priority' },
+          guidance: 'Use only from the task-list app when reprioritizing.',
+        },
+      ],
+    },
+    {
+      id: 'capture_task',
+      title: 'Capture a task',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'add_task' },
+          guidance: 'Ground the new task title and priority exactly.',
+        },
+      ],
+    },
+    {
+      id: 'complete_task',
+      title: 'Complete a task',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'complete_task' },
+          guidance: 'Confirm the exact grounded task with the user before completion.',
+        },
+      ],
+    },
+  ],
+  boundaries: [
+    'Never invent a task identifier.',
+    'Ground writes in the exact task and confirm completion with the user.',
+  ],
+  examples: [
+    { prompt: 'What should I do today?', workflow: 'review_tasks' },
+    { prompt: 'Add a follow-up with the vendor.', workflow: 'capture_task' },
+    { prompt: 'Finish the vendor follow-up.', workflow: 'complete_task' },
+  ],
+} as const satisfies AgentGuideSource;

package/skills/claude-code/examples/acme-tasks/src/server.ts

@@ -1,4 +1,5 @@
 import { annotations, server, tool, z } from '@noodleseed/one';
+import { ACME_TASKS_AGENT_GUIDE } from './agent-guide.js';
 
 // Acme Tasks is a fictional productivity app. It is a two-way (read + write) experience rather than a
 // top-of-funnel handoff: the top-3 prioritized user flows all complete in chat — Capture, Prioritize,
@@ -43,6 +44,7 @@ export default server(
   {
     title: 'Acme Tasks',
     version: '1.0.0',
+    agentGuide: ACME_TASKS_AGENT_GUIDE,
     // ChatGPT's stateless MCP lane cannot carry Noodle's standard confirmation form. Keep
     // confirm:true for capable/embedded hosts, but explicitly trust native host approval there.
     interactions: { confirmationFallback: 'host' },

package/skills/claude-code/examples/acme-tasks/test/server.test.ts

@@ -24,8 +24,37 @@ describe('acme-tasks example', () => {
     const manifest = await app.toManifest();
     const completeTask = manifest.tools.find((candidate) => candidate.name === 'complete_task');
     const addTask = manifest.tools.find((candidate) => candidate.name === 'add_task');
+    const setPriority = manifest.tools.find((candidate) => candidate.name === 'set_priority');
 
     expect(completeTask?.annotations?.confirm).toBe(true);
     expect(addTask?.annotations).not.toHaveProperty('confirm');
+    expect(setPriority?.visibility).toEqual(['app']);
+  });
+
+  it('teaches its three product workflows through one host-neutral agent guide', async () => {
+    const manifest = await app.toManifest();
+    const guide = manifest.server.agentGuide;
+
+    expect(guide?.workflows.map((workflow) => workflow.id)).toEqual([
+      'review_tasks',
+      'capture_task',
+      'complete_task',
+    ]);
+    expect(
+      guide?.workflows.flatMap((workflow) => workflow.steps.map((step) => step.capability.name)),
+    ).toEqual(expect.arrayContaining(['list_today', 'set_priority', 'add_task', 'complete_task']));
+    expect(
+      guide?.workflows
+        .find((workflow) => workflow.id === 'review_tasks')
+        ?.steps.map((step) => step.capability.name),
+    ).toContain('set_priority');
+    expect(
+      guide?.examples.every((example) =>
+        guide.workflows.some((workflow) => workflow.id === example.workflow),
+      ),
+    ).toBe(true);
+    expect(guide?.boundaries.some((boundary) => boundary.toLowerCase().includes('confirm'))).toBe(
+      true,
+    );
   });
 });

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

@@ -60,6 +60,13 @@ const api = connector('noodleseed_app_api')
   });
 ```
 
+`delegatedTokenExchange` consumes a verified customer caller; an MCP access mode does not create one. The
+server must declare `customerAuth.*(...)` or `embeddedAssistant(...)` so Noodle Seed can establish the caller
+subject, issuer, and audience. Otherwise `noodle validate`, `noodle auth doctor`, and deploy fail early with
+`delegated_token_exchange_identity_required`, before secrets are resolved or any connector egress. A
+successful local Devtools exchange is not evidence that the hosted server has an identity source. Devtools
+supplies a separate, loopback-only local identity context that is never accepted by hosted deployment.
+
 At both connector and operation level, auth must be omitted or use `delegatedTokenExchange`. The compiler
 validates the concrete connector definition emitted from TypeScript, including connector defaults and
 operation overrides, and reports the exact failing auth path and kind. Do not keep a bearer, API-key,

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

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

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

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

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

@@ -230,6 +230,8 @@ Role values are trusted only from the explicitly configured claim path (or the p
 
 Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream:
 
+`delegatedTokenExchange` consumes a verified customer caller; an MCP access mode does not create one. The server must declare `customerAuth.*(...)` or `embeddedAssistant(...)` so Noodle can establish the caller subject, issuer, and audience. Otherwise `noodle validate`, `noodle auth doctor`, and deploy fail early with `delegated_token_exchange_identity_required`, before secrets are resolved or any connector egress. A successful local Devtools exchange is not evidence that the hosted server has an identity source. Devtools supplies a separate, loopback-only local identity context that is never accepted by hosted deployment.
+
 - **`delegatedTokenExchange`** — your own API. The platform signs a short-lived, verifiable assertion of the signed-in user and exchanges it at a token endpoint you implement (RFC 8693). It works with verified customer OIDC identities and the built-in Firebase/Microsoft adapters; no per-user OAuth enrollment. Embedded-assistant sessions can bind customer-routed connectors when the authenticated embedding backend resolves each route from server-owned tenancy data and passes it during session exchange. Browser input, page context, session claims, and tool arguments cannot supply or override that private route authority.
 - **`delegatedOAuth` with `provider: "firebase" | "microsoft"`** — Noodle-managed bridge providers using stored per-user refresh tokens. Requires the matching `customerAuth` bridge; any other provider string is the compile error `unsupported_delegated_provider`.
 - **`delegatedSessionCookie`** — Firebase-managed session-cookie apps only; not a generic mechanism.

package/skills/claude-code/references/compile-errors.md

@@ -73,4 +73,11 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `customer_endpoint_policy_conflict` | Give every reachable declaration of this endpoint key one identical policy, or rename keys whose allowed origins differ. |
 | `customer_endpoint_routing_inconsistent` | Regenerate the connector catalog so every action route includes all of its ordinary customer endpoint dependencies. |
 | `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
-| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `agent_guide_invalid` | Correct the product guide shape in `server(..., { agentGuide })` using non-empty bounded prose and symbolic references. |
+| `agent_guide_duplicate_workflow` | Give every `agentGuide.workflows` entry a unique lowercase underscore id. |
+| `agent_guide_duplicate_example` | Keep each agent-guide prompt and workflow pairing unique. |
+| `agent_guide_example_workflow_missing` | Point the example workflow at an existing `agentGuide.workflows` id. |
+| `agent_guide_capability_missing` | Correct the capability kind/name in `server(..., { agentGuide })` to a declared MCP capability. |
+| `agent_guide_capability_kind` | Correct the capability kind/name in `server(..., { agentGuide })` to match its declared MCP capability. |
+| `app_package_sensitive_content` | Remove the credential value; reference managed config by name only. |

package/skills/claude-code/references/product-agent-guides.md

@@ -0,0 +1,11 @@
+# Product agent guides
+
+Author one optional `agentGuide` in `server(name, { agentGuide, ... }, definitions)` when an agent needs product-level workflow guidance beyond individual MCP capability descriptions. It is host-neutral and TypeScript-only.
+
+The guide contains `description`, `useWhen`, named `workflows`, optional `boundaries`, and optional example prompt-to-workflow mappings. Each workflow step references a declared `tool`, `resource`, or `prompt` by symbolic `{ kind, name }`; do not duplicate schemas, connector bindings, URLs, credentials, or raw runtime data.
+
+Keep identifiers within 200 characters and prose within 4,000 characters. A guide has at most 32 `useWhen` entries, 32 workflows, 64 steps per workflow, 64 boundaries, and 64 examples. The compiler rejects an App Package whose bounded derived MCP surface would still exceed its artifact ceiling.
+
+Use `server.instructions` for a concise live MCP-session primer. Noodle-owned workflow skills teach how to build and operate Noodle projects; a product guide teaches agents how to use this one deployed product. Compilation validates references and produces an App Package sibling while the RuntimeArtifact deliberately omits guide prose.
+
+Recover `agent_guide_*` errors by correcting the guide shape, workflow IDs, and capability kind/name. Remove any credential-shaped value: managed config is referenced by name only.

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.62.1 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:d83543258e5ca5ff -->
+<!-- noodle-skill version:0.63.1 hash:88e3ae21d02f2fe7 -->
 
 # Noodle Seed
 
@@ -56,6 +56,7 @@ Inside the installed plugin, perform mapped steps with `noodle-readiness` tools
 This is a lookup catalog, not a discovery checklist. Return here only when the selected primary route names a missing technical detail:
 
 - `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
+- `references/product-agent-guides.md` — author one host-neutral guide for a product MCP surface.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.

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.62.1 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.63.1 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

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

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.62.1 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.63.1 hash:f7fa54992c8d7692 -->
 
 # 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.62.1 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.63.1 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

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.62.1 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.63.1 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

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

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

package/skills/codex/examples/acme-tasks/src/agent-guide.ts

@@ -0,0 +1,53 @@
+import type { AgentGuideSource } from '@noodleseed/one';
+
+/** Product guidance is authored once for the full Acme Tasks MCP surface. */
+export const ACME_TASKS_AGENT_GUIDE = {
+  description: 'Use Acme Tasks to review, capture, prioritize, and complete the team task list.',
+  useWhen: [
+    'The user asks about their Acme work items.',
+    'The user wants to capture or finish an Acme task.',
+  ],
+  workflows: [
+    {
+      id: 'review_tasks',
+      title: 'Review today’s tasks',
+      intent: 'Ground the task list before taking action.',
+      steps: [
+        { capability: { kind: 'tool', name: 'list_today' } },
+        {
+          capability: { kind: 'tool', name: 'set_priority' },
+          guidance: 'Use only from the task-list app when reprioritizing.',
+        },
+      ],
+    },
+    {
+      id: 'capture_task',
+      title: 'Capture a task',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'add_task' },
+          guidance: 'Ground the new task title and priority exactly.',
+        },
+      ],
+    },
+    {
+      id: 'complete_task',
+      title: 'Complete a task',
+      steps: [
+        {
+          capability: { kind: 'tool', name: 'complete_task' },
+          guidance: 'Confirm the exact grounded task with the user before completion.',
+        },
+      ],
+    },
+  ],
+  boundaries: [
+    'Never invent a task identifier.',
+    'Ground writes in the exact task and confirm completion with the user.',
+  ],
+  examples: [
+    { prompt: 'What should I do today?', workflow: 'review_tasks' },
+    { prompt: 'Add a follow-up with the vendor.', workflow: 'capture_task' },
+    { prompt: 'Finish the vendor follow-up.', workflow: 'complete_task' },
+  ],
+} as const satisfies AgentGuideSource;

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

@@ -1,4 +1,5 @@
 import { annotations, server, tool, z } from '@noodleseed/one';
+import { ACME_TASKS_AGENT_GUIDE } from './agent-guide.js';
 
 // Acme Tasks is a fictional productivity app. It is a two-way (read + write) experience rather than a
 // top-of-funnel handoff: the top-3 prioritized user flows all complete in chat — Capture, Prioritize,
@@ -43,6 +44,7 @@ export default server(
   {
     title: 'Acme Tasks',
     version: '1.0.0',
+    agentGuide: ACME_TASKS_AGENT_GUIDE,
     // ChatGPT's stateless MCP lane cannot carry Noodle's standard confirmation form. Keep
     // confirm:true for capable/embedded hosts, but explicitly trust native host approval there.
     interactions: { confirmationFallback: 'host' },

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

@@ -24,8 +24,37 @@ describe('acme-tasks example', () => {
     const manifest = await app.toManifest();
     const completeTask = manifest.tools.find((candidate) => candidate.name === 'complete_task');
     const addTask = manifest.tools.find((candidate) => candidate.name === 'add_task');
+    const setPriority = manifest.tools.find((candidate) => candidate.name === 'set_priority');
 
     expect(completeTask?.annotations?.confirm).toBe(true);
     expect(addTask?.annotations).not.toHaveProperty('confirm');
+    expect(setPriority?.visibility).toEqual(['app']);
+  });
+
+  it('teaches its three product workflows through one host-neutral agent guide', async () => {
+    const manifest = await app.toManifest();
+    const guide = manifest.server.agentGuide;
+
+    expect(guide?.workflows.map((workflow) => workflow.id)).toEqual([
+      'review_tasks',
+      'capture_task',
+      'complete_task',
+    ]);
+    expect(
+      guide?.workflows.flatMap((workflow) => workflow.steps.map((step) => step.capability.name)),
+    ).toEqual(expect.arrayContaining(['list_today', 'set_priority', 'add_task', 'complete_task']));
+    expect(
+      guide?.workflows
+        .find((workflow) => workflow.id === 'review_tasks')
+        ?.steps.map((step) => step.capability.name),
+    ).toContain('set_priority');
+    expect(
+      guide?.examples.every((example) =>
+        guide.workflows.some((workflow) => workflow.id === example.workflow),
+      ),
+    ).toBe(true);
+    expect(guide?.boundaries.some((boundary) => boundary.toLowerCase().includes('confirm'))).toBe(
+      true,
+    );
   });
 });

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

@@ -60,6 +60,13 @@ const api = connector('noodleseed_app_api')
   });
 ```
 
+`delegatedTokenExchange` consumes a verified customer caller; an MCP access mode does not create one. The
+server must declare `customerAuth.*(...)` or `embeddedAssistant(...)` so Noodle Seed can establish the caller
+subject, issuer, and audience. Otherwise `noodle validate`, `noodle auth doctor`, and deploy fail early with
+`delegated_token_exchange_identity_required`, before secrets are resolved or any connector egress. A
+successful local Devtools exchange is not evidence that the hosted server has an identity source. Devtools
+supplies a separate, loopback-only local identity context that is never accepted by hosted deployment.
+
 At both connector and operation level, auth must be omitted or use `delegatedTokenExchange`. The compiler
 validates the concrete connector definition emitted from TypeScript, including connector defaults and
 operation overrides, and reports the exact failing auth path and kind. Do not keep a bearer, API-key,

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

package/skills/codex/references/authoring-workflow.md

@@ -230,6 +230,8 @@ Role values are trusted only from the explicitly configured claim path (or the p
 
 Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream:
 
+`delegatedTokenExchange` consumes a verified customer caller; an MCP access mode does not create one. The server must declare `customerAuth.*(...)` or `embeddedAssistant(...)` so Noodle can establish the caller subject, issuer, and audience. Otherwise `noodle validate`, `noodle auth doctor`, and deploy fail early with `delegated_token_exchange_identity_required`, before secrets are resolved or any connector egress. A successful local Devtools exchange is not evidence that the hosted server has an identity source. Devtools supplies a separate, loopback-only local identity context that is never accepted by hosted deployment.
+
 - **`delegatedTokenExchange`** — your own API. The platform signs a short-lived, verifiable assertion of the signed-in user and exchanges it at a token endpoint you implement (RFC 8693). It works with verified customer OIDC identities and the built-in Firebase/Microsoft adapters; no per-user OAuth enrollment. Embedded-assistant sessions can bind customer-routed connectors when the authenticated embedding backend resolves each route from server-owned tenancy data and passes it during session exchange. Browser input, page context, session claims, and tool arguments cannot supply or override that private route authority.
 - **`delegatedOAuth` with `provider: "firebase" | "microsoft"`** — Noodle-managed bridge providers using stored per-user refresh tokens. Requires the matching `customerAuth` bridge; any other provider string is the compile error `unsupported_delegated_provider`.
 - **`delegatedSessionCookie`** — Firebase-managed session-cookie apps only; not a generic mechanism.

package/skills/codex/references/compile-errors.md

@@ -73,4 +73,11 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `customer_endpoint_policy_conflict` | Give every reachable declaration of this endpoint key one identical policy, or rename keys whose allowed origins differ. |
 | `customer_endpoint_routing_inconsistent` | Regenerate the connector catalog so every action route includes all of its ordinary customer endpoint dependencies. |
 | `unused_connector_alias` | A declared connector alias is never called; remove the unused `use` entry or wire it into a tool. |
-| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `arg_mismatch` | A connector call is missing or adds arguments; match the operation signature under `expected`/`got`. |
+| `agent_guide_invalid` | Correct the product guide shape in `server(..., { agentGuide })` using non-empty bounded prose and symbolic references. |
+| `agent_guide_duplicate_workflow` | Give every `agentGuide.workflows` entry a unique lowercase underscore id. |
+| `agent_guide_duplicate_example` | Keep each agent-guide prompt and workflow pairing unique. |
+| `agent_guide_example_workflow_missing` | Point the example workflow at an existing `agentGuide.workflows` id. |
+| `agent_guide_capability_missing` | Correct the capability kind/name in `server(..., { agentGuide })` to a declared MCP capability. |
+| `agent_guide_capability_kind` | Correct the capability kind/name in `server(..., { agentGuide })` to match its declared MCP capability. |
+| `app_package_sensitive_content` | Remove the credential value; reference managed config by name only. |

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

@@ -0,0 +1,11 @@
+# Product agent guides
+
+Author one optional `agentGuide` in `server(name, { agentGuide, ... }, definitions)` when an agent needs product-level workflow guidance beyond individual MCP capability descriptions. It is host-neutral and TypeScript-only.
+
+The guide contains `description`, `useWhen`, named `workflows`, optional `boundaries`, and optional example prompt-to-workflow mappings. Each workflow step references a declared `tool`, `resource`, or `prompt` by symbolic `{ kind, name }`; do not duplicate schemas, connector bindings, URLs, credentials, or raw runtime data.
+
+Keep identifiers within 200 characters and prose within 4,000 characters. A guide has at most 32 `useWhen` entries, 32 workflows, 64 steps per workflow, 64 boundaries, and 64 examples. The compiler rejects an App Package whose bounded derived MCP surface would still exceed its artifact ceiling.
+
+Use `server.instructions` for a concise live MCP-session primer. Noodle-owned workflow skills teach how to build and operate Noodle projects; a product guide teaches agents how to use this one deployed product. Compilation validates references and produces an App Package sibling while the RuntimeArtifact deliberately omits guide prose.
+
+Recover `agent_guide_*` errors by correcting the guide shape, workflow IDs, and capability kind/name. Remove any credential-shaped value: managed config is referenced by name only.

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.62.1 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.63.1 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.62.1 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.63.1 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications