@noodleseed/agent-kit 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "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.42.0 hash:0c1ebd532b9c2499 -->
+<!-- noodle-skill version:0.43.0 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 
@@ -35,7 +35,7 @@ Negative routing examples: “Inspect hosted logs/status” → `inspect-hosted`
 | Deploy, configure, connect with writes, change access, or roll back a hosted MCP service when explicitly requested | `deploying-mcp-services` | `references/deploy-and-ops.md` (`references/cli-commands.md`) | The requested hosted state is evidenced without claiming unperformed host or production checks. |
 | Embed a Noodle assistant in an existing SaaS or web application | `embedding-mcp-assistants` | `references/embedded-assistant.md` (`references/authoring-workflow.md`) | The requested embed boundary works with verified identity and credential separation at the tested level. |
 | Prepare or submit an integration to a host directory | `publishing-mcp-integrations` | `references/publishing.md` (`references/app-directory-compliance.md`) | The requested submission evidence is complete and any host-review uncertainty is explicit. |
-| Report a Noodle Seed bug, documentation gap, or product improvement | `reporting-noodle-feedback` | `references/feedback.md` (None) | A sanitized command is shown to the user and is submitted only after explicit approval. |
+| Report a Noodle Seed bug, documentation gap, or product improvement | `reporting-noodle-feedback` | `references/feedback.md` (None) | A sanitized dry-run preview and exact live command are shown, then one submission occurs only after explicit approval. |
 
 ## Common machine loop
 
@@ -57,7 +57,8 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.
 - `references/build-an-mcp-server.md` — outcome-first workflow for a focused, tested, model-facing MCP product.
-- `references/authoring-workflow.md` — input paths, fit checks, connector patterns, authentication, tool design, testing, and managed config.
+- `references/authoring-workflow.md` — input paths, fit checks, connector patterns, authentication, invocation context, testing, and managed config.
+- `references/tool-design.md` — intent-shaped tools, titles and annotations, bounded outputs, tool-surface budget, and context provisioning.
 - `references/embedded-assistant.md` — HTTPS origins, managed model config, deploy sequencing, session exchange, browser mounting, and credential boundaries.
 - `references/connect-an-api.md` — secure credentials, probe the live API, model the observed shape, and prove real output.
 - `references/build-an-mcp-app.md` — product-fit, output-boundary, fallback, and evidence workflow for an MCP App.
@@ -75,7 +76,7 @@ This is a lookup catalog, not a discovery checklist. Return here only when the s
 
 ## Product feedback
 
-When you discover a bug, missing capability, misleading doc, or improvement idea, draft one sanitized `noodle feedback` command per finding. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given. Follow `references/feedback.md`; never include customer code, secrets, personal data, or identifying project details.
+When you discover a bug, missing capability, misleading doc, or improvement idea, discover current fields with `noodle commands --json`, draft and sanitize one finding, then run `noodle feedback ... --dry-run --json`. Inspect and show the exact normalized submission, diagnostics, private destination, and POSIX-safely quoted live command. Ask for explicit approval of that exact proposal; do not submit it until approval. Then submit once without `--dry-run`. Follow `references/feedback.md`; never include customer code, secrets, personal data, or identifying project details, and never auto-login or retry-loop.
 
 ## Safety
 

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.42.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.43.0 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.42.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.43.0 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 credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.42.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.43.0 hash:1e86b8704f407bd3 -->
 
 # 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.42.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.43.0 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.42.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.43.0 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.42.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.43.0 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.42.0 hash:5d8f40f904d6ab4b -->
+<!-- noodle-skill version:0.43.0 hash:5d8f40f904d6ab4b -->
 
 # embedding-mcp-assistants
 

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

@@ -53,13 +53,16 @@ export default server(
   },
   [
     tool('show_menu', {
+      title: 'Show the menu',
       description: 'Show the Acme Bistro menu and render the ordering widget.',
       annotations: readOnly,
       input: z.object({ customer: z.string().default('Guest') }),
       output: z.object({
         status: z.string(),
         customer: z.string(),
-        items: z.array(menuItemOutput),
+        // Bounded list: the menu is a fixed catalog, so the ceiling is declared on the shape rather
+        // than taken as a pagination input. `noodle check` reports `tool_design_output_bounds`.
+        items: z.array(menuItemOutput).max(50),
       }),
       fulfil: ({ input }) => ({
         status: `Acme Bistro menu is ready for ${input.customer}. Build the order here; pay at checkout.`,
@@ -125,6 +128,7 @@ export default server(
     // The only handoff: payment. The widget computes the total (live React) and passes a url-safe cart
     // token + total; the card is entered on Acme's PCI-scoped checkout, never in chat.
     tool('create_checkout', {
+      title: 'Create checkout',
       description:
         'Create the Acme Bistro payment checkout link for the current order. Pass a url-safe cart token ' +
         'and the numeric total computed in the widget. Payment happens off-app; the card never reaches this app.',

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

@@ -116,6 +116,7 @@ export default server(
   },
   [
     tool('discover_getaways', {
+      title: 'Discover getaways',
       description:
         'Suggest Acme Getaways destinations for a vibe and month and render a discovery carousel.',
       annotations: readOnly,
@@ -125,7 +126,9 @@ export default server(
         vibe: z.string(),
         month: z.string(),
         travelers: z.number(),
-        options: z.array(destinationOutput),
+        // Bounded list: the curated catalog is fixed and small, and the declared ceiling tells the
+        // model and host the payload cannot grow. `noodle check` reports `tool_design_output_bounds`.
+        options: z.array(destinationOutput).max(20),
       }),
       // The carousel presents Acme's curated catalog; the model narrates which fit the stated vibe.
       // (A tool cannot filter on an input value — that is connector/flow work — so all are returned.)
@@ -154,6 +157,7 @@ export default server(
       },
     }),
     tool('create_handoff', {
+      title: 'Create booking handoff',
       description:
         'Create the Acme booking deep link for a chosen destination, carrying the configured trip. ' +
         'Pass the destination id (url-safe slug, e.g. "coral_bay") and its display name.',

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

@@ -62,10 +62,13 @@ export default server(
       description: 'Show today’s Acme Tasks and render the task-list widget.',
       annotations: readOnly,
       input: z.object({ focus: z.string().default('today') }),
+      // Bound the list output. A recorded `fulfil` cannot slice an array, so the honest bound here is
+      // a cap on the shape itself; a connector-backed list takes a pagination input instead (see the
+      // `weather` example). `noodle check` reports an unbounded array as `tool_design_output_bounds`.
       output: z.object({
         status: z.string(),
         focus: z.string(),
-        tasks: z.array(taskOutput),
+        tasks: z.array(taskOutput).max(20),
       }),
       fulfil: ({ input }) => ({
         status: `Acme Tasks for ${input.focus}: ${today.length} open items, highest priority first.`,

package/skills/claude-code/examples/customer-auth/src/server.ts

@@ -142,8 +142,12 @@ export default server(
       description: 'List the NoodleSeed.com organizations the signed-in customer belongs to.',
       contextProvider: true,
       input: z.object({}),
+      // The dev app API returns every organization for the signed-in customer in one response, with no
+      // page parameter to pass through, so the bound is declared on the shape. A customer belongs to a
+      // handful of organizations; `noodle check` reports an unbounded list as
+      // `tool_design_output_bounds`.
       output: z.object({
-        organizations: z.array(z.unknown()),
+        organizations: z.array(z.unknown()).max(100),
       }),
       annotations: annotations.readOnly(),
       fulfil({ connectors }) {

package/skills/claude-code/examples/food-ordering/src/server.ts

@@ -132,7 +132,9 @@ const menuItemShape = z.object({
   name: z.string(),
   price: z.number(),
   description: z.string(),
-  modifiers: z.array(z.string()),
+  // Nested lists count toward the output budget too: unbounded modifiers multiply by every item in a
+  // menu payload, so the ceiling is declared here rather than only on the outer array.
+  modifiers: z.array(z.string()).max(10),
 });
 
 const cartOutput = z.object({
@@ -240,6 +242,7 @@ export default server(
   },
   [
     tool('open_ordering', {
+      title: 'Open food ordering',
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
@@ -247,11 +250,14 @@ export default server(
         query: z.string().optional(),
         customer: z.string().default('Guest'),
       }),
+      // List outputs declare a ceiling so a host and the model both know the payload is bounded.
+      // A recorded `fulfil` cannot slice, so the cap belongs on the shape; connector-backed lists take
+      // a pagination input instead. `noodle check` reports `tool_design_output_bounds` without one.
       output: z.object({
         status: z.string(),
         customer: z.string(),
-        stores: z.array(storeShape),
-        featuredItems: z.array(menuItemShape),
+        stores: z.array(storeShape).max(20),
+        featuredItems: z.array(menuItemShape).max(20),
         localDate: z.string(),
         serviceArea: z.string(),
         fallback: z.string(),
@@ -371,16 +377,18 @@ export default server(
       },
     }),
     tool('summarize_ordering_options', {
+      title: 'Summarize ordering options',
       description: 'Summarize available stores and menu examples without opening the widget.',
       annotations: readOnly,
       input: z.object({}),
       output: z.object({
-        stores: z.array(storeShape),
-        featuredItems: z.array(menuItemShape),
+        stores: z.array(storeShape).max(20),
+        featuredItems: z.array(menuItemShape).max(20),
       }),
       fulfil: () => ({ stores, featuredItems: menu }),
     }),
     tool('plan_order', {
+      title: 'Plan an order',
       description:
         'Collect a fulfilment method and requested date as structured input, then return a reviewable order plan without placing an order.',
       annotations: readOnly,
@@ -409,6 +417,7 @@ export default server(
       },
     }),
     tool('show_capabilities', {
+      title: 'Show capabilities',
       description: 'Return a concise summary for the standalone widget capability preview.',
       annotations: readOnly,
       input: z.object({}),

package/skills/claude-code/examples/gmail-multi-account/src/server.ts

@@ -35,10 +35,13 @@ const vacationOptionalFields = {
   start_time: epochMillis.optional(),
   end_time: epochMillis.optional(),
 };
+// One shared output shape for every tool: one entry per account the call fanned out to. The cap is
+// exactly the number of canonical accounts, so it is a true bound rather than a guess — `noodle check`
+// reports an unbounded array output as `tool_design_output_bounds`.
 const output = z.object({
-  results: z.array(
-    z.object({ account: z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT]), data: z.unknown() }),
-  ),
+  results: z
+    .array(z.object({ account: z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT]), data: z.unknown() }))
+    .max(2),
 });
 
 const gmail = gmailConnector();
@@ -84,6 +87,7 @@ export default server(
   },
   [
     tool('search_messages', {
+      title: 'Search messages',
       description: 'Search one connected Gmail account or the canonical personal-and-work pair.',
       input: z.object({
         accounts: readAccounts,
@@ -119,6 +123,7 @@ export default server(
       },
     }),
     tool('get_message', {
+      title: 'Get message',
       description: 'Get one Gmail message from one connected account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -154,6 +159,7 @@ export default server(
       },
     }),
     tool('get_thread', {
+      title: 'Get thread',
       description: 'Get one Gmail thread from one connected account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -189,6 +195,7 @@ export default server(
       },
     }),
     tool('list_drafts', {
+      title: 'List drafts',
       description: 'List drafts from one connected Gmail account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -224,6 +231,7 @@ export default server(
       },
     }),
     tool('get_draft', {
+      title: 'Get draft',
       description: 'Get one draft from one connected Gmail account or both canonical accounts.',
       input: z.object({
         accounts: readAccounts,
@@ -259,6 +267,7 @@ export default server(
       },
     }),
     tool('get_vacation', {
+      title: 'Get vacation responder',
       description: 'Read vacation-responder settings from one connected account or both accounts.',
       input: z.object({ accounts: readAccounts }),
       output,
@@ -281,6 +290,7 @@ export default server(
       },
     }),
     tool('create_draft', {
+      title: 'Create draft',
       description:
         'Create a Gmail draft in exactly one selected account from a base64url MIME message.',
       annotations: confirmedWrite,
@@ -301,6 +311,7 @@ export default server(
       },
     }),
     tool('update_draft', {
+      title: 'Update draft',
       description:
         'Replace a Gmail draft in exactly one selected account with a base64url MIME message.',
       annotations: confirmedWrite,
@@ -322,6 +333,7 @@ export default server(
       },
     }),
     tool('send_draft', {
+      title: 'Send draft',
       description: 'Send an existing Gmail draft from exactly one selected account.',
       annotations: confirmedWrite,
       input: z.object({ accounts: writeAccounts, draft_id: identifier }),
@@ -341,6 +353,7 @@ export default server(
       },
     }),
     tool('modify_message_labels', {
+      title: 'Change message labels',
       description: 'Add or remove Gmail label ids on one message in exactly one selected account.',
       annotations: confirmedWrite,
       input: z.object({
@@ -370,6 +383,7 @@ export default server(
       },
     }),
     tool('archive_message', {
+      title: 'Archive message',
       description: 'Archive one Gmail message in exactly one account by removing INBOX.',
       annotations: confirmedWrite,
       input: z.object({ accounts: writeAccounts, message_id: identifier }),
@@ -389,6 +403,7 @@ export default server(
       },
     }),
     tool('send_message', {
+      title: 'Send message',
       description: 'Send one base64url MIME message from exactly one selected Gmail account.',
       annotations: confirmedWrite,
       input: z.object({
@@ -413,6 +428,7 @@ export default server(
       },
     }),
     tool('trash_message', {
+      title: 'Move message to trash',
       description: 'Move one Gmail message to trash in exactly one account. This is reversible.',
       annotations: confirmedTrash,
       input: z.object({ accounts: writeAccounts, message_id: identifier }),
@@ -432,6 +448,7 @@ export default server(
       },
     }),
     tool('update_vacation', {
+      title: 'Update vacation responder',
       description: 'Update vacation-responder settings on exactly one selected Gmail account.',
       annotations: confirmedWrite,
       input: z.object({

package/skills/claude-code/examples/hello/README.md

@@ -10,8 +10,10 @@ When an installed Noodle Developer plugin drives this example, its skill runs th
 Do not install or update a global CLI: the coding agent writes and tests this source while Noodle
 guides and operates the validate, preview, deploy, inspect, and debug workflow.
 If that agent discovers a Noodle Seed product gap while working, the installed skill prepares a
-sanitized `noodle feedback` proposal, discovers current fields from `noodle commands --json`, and
-submits it only after showing the exact command and receiving explicit user approval.
+sanitized `noodle feedback` proposal, discovers current fields from `noodle commands --json`, runs
+`--dry-run --json` to inspect the exact normalized submission, diagnostics, and private destination,
+then shows a POSIX-safely quoted live command. It submits once without `--dry-run` only after explicit
+user approval of that exact preview; it never auto-logs in or retry-loops.
 Every `--json` command writes its canonical success or failure envelope to stdout and leaves stderr
 empty. One-shot commands write one envelope; streaming commands write NDJSON snapshot, event, and
 terminal-failure envelopes so agents can parse each line independently.

package/skills/claude-code/examples/hello/src/server.ts

@@ -14,6 +14,9 @@ export default server(
   },
   [
     tool('greet', {
+      // Every model-visible tool declares a title: hosts show it in tool pickers and confirmation
+      // prompts, and both consumer directories reject tools without one.
+      title: 'Greet someone',
       description: 'Greet someone by name.',
       input: z.object({
         // Defaults are advertised to the model and applied at runtime when the argument is omitted.

package/skills/claude-code/examples/weather/src/server.ts

@@ -189,6 +189,7 @@ export default server(
   },
   [
     tool('weather_briefing', {
+      title: 'Weather briefing',
       description:
         'Look up a city, fetch its current weather, and return a human-readable briefing. Runs a ' +
         'three-step flow: geocode the city, fetch the forecast, then derive the briefing in a sandboxed compute step.',
@@ -233,14 +234,21 @@ export default server(
     // the whole array; the compute connector narrows each element to the two fields the model speaks
     // from. Append new tools AFTER existing ones so `tools[0]` stays stable for host harnesses.
     tool('search_places', {
+      title: 'Search places',
       description:
         'Search a place name and return the matching locations as a list of { id, label } options.',
-      input: z.object({ query: z.string() }),
+      // Bound the list at the source: `limit` is capped in the schema and passed through to the
+      // upstream `count` parameter, so the model can never pull an unbounded page into its context.
+      // `noodle check` reports an unbounded array output as `tool_design_output_bounds`.
+      input: z.object({
+        query: z.string(),
+        limit: z.number().int().min(1).max(10).default(5),
+      }),
       output: z.object({
         places: z.array(z.object({ id: z.string(), label: z.string() })),
       }),
       fulfil: ({ input, connectors }) => {
-        const found = connectors.geo.search_list({ name: input.query });
+        const found = connectors.geo.search_list({ name: input.query, count: input.limit });
         const narrowed = connectors.places.narrow({ results: found.results });
         return { places: narrowed.places };
       },

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.42.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.43.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

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

@@ -8,7 +8,6 @@
 - Connectors
 - HTTP connector example (full server)
 - Delegated downstream auth (call your API as the signed-in user)
-- Design tools for the model
 - Invocation context
 - Compute connector example
 - Tests
@@ -173,65 +172,7 @@ Diagnose statically with `noodle auth doctor`; set a short-lived real customer t
 
 ## Design tools for the model
 
-Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
-
-- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
-- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
-- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
-
-This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
-
-```ts
-import { connector, secret, server, tool, z } from '@noodleseed/one';
-
-const tasks = connector('tasks').version('1.0.0').http({
-  baseUrl: 'https://api.tasks.example',
-  allowedOrigins: ['https://api.tasks.example'],
-  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
-  operations: {
-    search_tasks: {
-      type: 'read',
-      method: 'GET',
-      path: '/tasks',
-      query: ['query'],
-      input: z.object({ query: z.string() }),
-      output: z.object({ matches: z.array(z.unknown()) }),
-      response: { matches: '${response.results}' },
-    },
-    close_task: {
-      type: 'action',
-      method: 'POST',
-      path: '/tasks/{id}/close',
-      input: z.object({ id: z.string() }),
-      output: z.object({ ok: z.boolean() }),
-      response: { ok: '${response.ok}' },
-    },
-  },
-});
-
-export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
-  tool('find_tasks', {
-    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
-    input: z.object({ query: z.string() }),
-    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
-    fulfil: ({ input, connectors }) => {
-      const found = connectors.tasks.search_tasks({ query: input.query });
-      return { matches: found.matches };
-    },
-  }),
-  tool('complete_task', {
-    description: 'Mark a task complete by its id (get the id from find_tasks).',
-    input: z.object({ id: z.string() }),
-    output: z.object({ ok: z.boolean() }),
-    fulfil: ({ input, connectors }) => {
-      const result = connectors.tasks.close_task({ id: input.id });
-      return { ok: result.ok };
-    },
-  }),
-]);
-```
-
-The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
+Shape tools around what a user says, not 1:1 around API endpoints. `references/tool-design.md` owns the doctrine: intent-shaped tools, titles and annotations, bounded outputs, a small tool surface, and deliberate context.
 
 ## Invocation context
 

package/skills/claude-code/references/build-an-mcp-server.md

@@ -22,7 +22,7 @@ Establish only the inputs needed for the requested stopping point. Follow `refer
 1. **Confirm conversational fit.** Name one to three focused jobs where saying the request is easier than navigating the underlying system, and identify the data or action the model cannot provide by itself.
 2. **Define the product contract.** For each job, write the user phrase, the intent-shaped tool or resource, its minimal typed input, the useful output, read/write effect, and backing operation. Design for user intent, not a 1:1 API endpoint wrapper.
 3. **Choose the smallest implementation.** Use native tools, resources, or prompts for local/static behavior; add a connector only when external data or actions are required. Keep response output small and model-readable.
-4. **Author in TypeScript.** Follow `references/authoring-workflow.md` for connector and flow patterns and `references/sdk-surface.md` for exact builders. These are this route’s complete canonical support set; use the router lookup catalog only when observed evidence names a different concern.
+4. **Author in TypeScript.** Follow `references/authoring-workflow.md` for connector and flow patterns, `references/tool-design.md` for the model-facing tool surface, and `references/sdk-surface.md` for exact builders. These are this route’s complete canonical support set; use the router lookup catalog only when observed evidence names a different concern.
 5. **Validate and repair.** Run `noodle validate --json`. Parse `error.errors[]`, repair the cited `path`, and rerun validation. Consult the lookup catalog only for the specific reported error code; do not open another reference speculatively.
 6. **Run the local smoke.** After validation succeeds, run `noodle test --json` and repair any failure at that evidence layer.
 7. **Prove external behavior.** For connector-backed reads, set credentials through the effective local target and run a safe representative `noodle tools call`. Confirm populated mapped fields from real output, not merely successful registration.

package/skills/claude-code/references/cli-commands.md

@@ -27,7 +27,7 @@ Developer-facing `noodle` commands, grouped by area. Local authoring commands (`
 | `noodle import` | Import an OpenAPI spec into a starter `server.ts`. |
 | `noodle export` | Compile locally and write the portable manifest JSON (no service). |
 | `noodle validate` | Author-time compile/schema/connector check; no service (`--json`, `--fix-prompt`). |
-| `noodle check` | Check MCP Apps/widget readiness; no service. |
+| `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. |
 
 ## Local run & inspect

package/skills/claude-code/references/connect-an-api.md

@@ -157,8 +157,12 @@ Local `dev`, smoke commands, secrets, and variables resolve one effective target
 noodle secrets set SOME_API_KEY --runtime local --from-env SOME_API_KEY
 # Explicit flags remain available when intentionally testing a different local target:
 noodle secrets set SOME_API_KEY --runtime local --scope env --org <org> --app <app> --env <env> --from-env SOME_API_KEY
+# Configuring a deployed environment is a different store — say so:
+noodle secrets set SOME_API_KEY --runtime cloud --scope env --org <org> --app <app> --env <env> --from-env SOME_API_KEY
 ```
 
+`--runtime` is required whenever `--org`, `--app`, and `--env` together name a complete hosted target: a command that looks remote must never fall back to writing `.env.noodle`. Omitting it fails with `runtime_required` before anything is written.
+
 Local secrets live in `./.env.noodle` (never commit it). A required `secret(...)` or `variable(...)` that cannot resolve fails boot closed. `noodle tools call` / `noodle test` / `noodle dev` / `noodle devtools` stop before exposing an empty endpoint and print the exact effective target plus recovery command.
 
 ### Prove real output

package/skills/claude-code/references/embedded-assistant.md

@@ -91,9 +91,9 @@ Give every business action a portable `tool(..., { title: "Complete task", descr
 Local MCP authoring and tests need no account, but an external browser embed needs an active assistant-enabled deployment before a backend client can be created. Set the model values on the target org/app/env, then deploy:
 
 ```sh
-noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --org <org> --app <app> --env <env> --value <https-model-base-url>
-noodle variables set ASSISTANT_MODEL --scope env --org <org> --app <app> --env <env> --value <model>
-noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --org <org> --app <app> --env <env> --from-env ASSISTANT_MODEL_API_KEY
+noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --runtime cloud --org <org> --app <app> --env <env> --value <https-model-base-url>
+noodle variables set ASSISTANT_MODEL --scope env --runtime cloud --org <org> --app <app> --env <env> --value <model>
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --runtime cloud --org <org> --app <app> --env <env> --from-env ASSISTANT_MODEL_API_KEY
 noodle deploy --org <org> --app <app> --env <env>
 ```
 

package/skills/claude-code/references/feedback.md

@@ -1,6 +1,6 @@
 # Send product feedback
 
-When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in Noodle Seed’s private tracker, so the user must make an informed choice. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given.
+When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in the Noodle Seed private feedback tracker, so the user must make an informed choice. Preview the exact normalized submission locally, show it with the exact live command, and ask for explicit user approval. Do not submit it until approval is given.
 
 ## Contents
 
@@ -26,20 +26,22 @@ Do not batch several findings into one proposal, and do not re-propose the same
 
 ## Approval workflow
 
-1. Draft and sanitize the title, message, labels, and exact shell command.
-2. Show the user the exact command and explain that it sends the shown content plus CLI version, OS/platform, and Node version to Noodle Seed’s private tracker.
-3. Ask for explicit user approval. Do not run, submit, or send anything until the user clearly approves that exact proposal.
-4. After approval, run it once. If authentication is missing, report that feedback was not sent and offer the normal `noodle login` path; never sign in or retry without direction.
+1. Discover the current positional arguments, flags, choices, defaults, and limits from `noodle commands --json`; `noodle feedback --help` is the human-readable view. Do not guess or rely on a remembered catalog.
+2. Draft one finding, then sanitize its title and message using the rules below.
+3. Run the proposal with `--dry-run --json`. This local preview needs no login and sends nothing. Parse `{"ok":true,"data":{"mode":"preview","willSubmit":false,"destination":"Noodle Seed private feedback tracker","submission":{...}}}`.
+4. Inspect the complete `submission`, including its normalized defaults and automatically attached diagnostics. Show the user the exact previewed proposal, its `destination`, and a POSIX-safely quoted live command containing the same fields but without `--dry-run`.
+5. Ask for explicit approval of that exact previewed proposal. If the user changes any field, preview the changed proposal again before asking.
+6. Only after approval, submit it once by running the disclosed live command without `--dry-run`. Never auto-login and never retry-loop. If authentication fails before the request or a rate limit denies it, report that nothing was sent. For `feedback_recording_failed`, report that no reference was returned and the outcome may be unknown; do not retry because the private issue might already exist.
 
 ## The command
 
 ```sh
-noodle feedback "resources list --json omits the truncated flag the docs promise" \
-  --title "resources list --json missing truncated flag" \
-  --type fix --severity P2 --area cli --json
+noodle feedback 'resources list --json omits the truncated flag the docs promise' \
+  --title 'resources list --json missing truncated flag' \
+  --type fix --severity P2 --area cli --dry-run --json
 ```
 
-This is an example only; build the exact command for the finding and show it before execution. Read `noodle feedback --help` for human-readable constraints or inspect `noodle commands --json` for the same machine-readable usage, enum, and length metadata instead of guessing accepted values. The message is required (1–4000 chars). Pass `--json` and parse the envelope: success is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop. The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected.
+This is a preview example only. Build the exact command for the finding using current `noodle commands --json` metadata, POSIX-quote every user-controlled value, and inspect the returned submission instead of reconstructing it. The message is required (1–4000 chars). The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected. After approval, the live success envelope is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop.
 
 ## Choose the structured fields