@noodleseed/agent-kit 0.90.0 → 0.92.0

package/skills/claude-code/connecting-apis-to-mcp/references/connect-an-api.md

@@ -0,0 +1,245 @@
+# Outcome
+
+Connect a real API to a focused MCP product using managed credentials, mappings derived from observed responses, and representative live-read evidence. A connector that merely compiles is not complete.
+
+## Contents
+
+- Use when
+- Do not use when
+- Required inputs
+- Workflow
+- Secure the key first
+- Probe the live API
+- Model the connector from the observed shape
+- Import and curate an upstream MCP server
+- Return a list
+- Create, update, delete
+- Design intent tools
+- Set the secret for local runs
+- Prove real output
+- Verification evidence
+- Recovery paths
+- Stop conditions
+
+## Use when
+
+- The user provides credentials, a reachable API, an OpenAPI document, or an upstream MCP endpoint and wants real MCP behavior backed by it.
+- Existing connector behavior compiles but still needs proof against the actual service and data shape.
+
+## Do not use when
+
+- The task is a local/static MCP capability with no external data source.
+- The user only wants a widget, deployment, publication, or diagnosis unrelated to API behavior; select that route.
+- Required credentials or authority are unavailable. Do not bypass authentication or substitute fabricated payloads for live evidence.
+
+## Required inputs
+
+Identify the API base URL, authentication scheme, one representative safe read, the user intent it serves, and either an OpenAPI document or one sanitized example response. For writes, also establish the effect, a safe test target, and explicit user approval before any live write.
+
+Do not guess or invent a field, schema, endpoint, pagination contract, or authentication behavior. Documentation is a hypothesis until a representative live read confirms the response actually returned.
+
+## Workflow
+
+### Secure the key first
+
+Never inline or log the key. Have the user put it in an environment variable, then store it as a
+managed secret and reference it only as `secret(...)`:
+
+```sh
+export SOME_API_KEY=…            # the user sets this; it never appears in a file or prompt
+noodle secrets set SOME_API_KEY --runtime local --from-env SOME_API_KEY   # same effective target as local dev/test/devtools
+```
+
+In `server.ts` the key is only ever `secret("SOME_API_KEY")` — keep the raw value out of code, tests,
+prompts, logs, and generated files.
+
+### Probe the live API
+
+Learn the actual response shape empirically. Two ways — capture one real example response per endpoint
+you will use, and read its field names, nesting, array shapes, pagination, and id-vs-label fields:
+
+- **With your own HTTP/shell tool** — call a representative read endpoint using the key **from the env
+  var**, never the literal (so it stays out of logs): `curl -H "Authorization: Bearer $SOME_API_KEY"
+  https://api.example.com/things`. Inspect the returned JSON.
+- **Noodle-native** — author a minimal read operation that maps the whole body (`response: { raw:
+  '${response}' }`), `noodle secrets set` the key, then `noodle tools call` it to see the real payload
+  in-process.
+
+### Model the connector from the observed shape
+
+Encode the API as an HTTP connector, mapping only the fields you actually saw into a small typed
+`output`:
+
+- `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`.
+- `auth: { kind: 'bearer', secret: secret('SOME_API_KEY') }` — or `{ kind: 'apiKey', header: 'X-API-Key',
+  secret: secret('SOME_API_KEY') }`. Never put the credential in operation `headers`.
+- Per operation: `method`, `path` (with `{id}` templates), `query: ["arg"]` for URL params, `input`,
+  `output`, and a `response` mapping whose `${response.path}` matches the real JSON — the parsed body is
+  bound directly to `${response}` (no `.body` envelope); use bracket indices for arrays
+  (`${response.results[0].id}`).
+
+The full connector shape, every `auth.kind`, and compute connectors are in
+`references/authoring-workflow.md`.
+
+### Import and curate an upstream MCP server
+
+Use an explicit import to discover the upstream tool surface once and generate TypeScript:
+
+```sh
+noodle import mcp https://store.example/api/mcp --name store --output store-app
+# When import discovery needs a credential, read it only from the environment:
+noodle import mcp https://store.example/api/mcp --name store \
+  --header-env Authorization=STORE_MCP_TOKEN
+```
+
+The importer freezes upstream tool names and normalized schemas into `.mcp({ operations })`; it never
+persists the import credential. Runtime calls only those declared operations and never runs `tools/list`.
+MCP annotations are untrusted hints, so every generated tool starts as a destructive confirmed action.
+Verify real behavior and deliberately narrow proven reads before accepting the generated source. Use
+`noodle import mcp <url> --output <dir> --check` in CI to detect upstream additions, removals, or schema
+changes without mutating source; its review labels drift additive, breaking, or metadata-only.
+
+Treat the imported connector operation as a backing-system contract, not the public tool design. Publish
+ordinary intent-shaped `tool(...)` capabilities with stable names and narrower schemas, normalize text or
+large upstream output through compute, and attach a normal Noodle React `view` when UI helps. Upstream
+`_meta`, resources, prompts, annotations, widgets, and CSP are never forwarded. A Noodle-owned widget may
+therefore enrich a headless upstream tool without trusting upstream executable UI.
+
+Managed endpoints require an exact managed origin allowlist. Configure each deployment with
+`variable(...)` and `secret(...)`; inbound MCP/OAuth bearer tokens are never reusable upstream credentials.
+The first release supports no auth, bearer, API key, and client credentials through the broker. Do not
+invent a delegated-user OAuth shortcut for an upstream MCP server.
+
+### Return a list
+
+Most real tools return a variable-length list (search results, a user’s tasks). Bind the **whole array** — a single `${response.path}` returns the referenced value verbatim, arrays included:
+
+```ts
+// The API returns { results: [ { id, name, country, … }, … ] }
+output: z.object({ places: z.array(z.unknown()) }),
+response: { places: '${response.results}' },
+```
+
+Three things that are easy to get subtly wrong:
+
+- **A response mapping cannot iterate.** There is no per-item / `map` / `item` construct, so you cannot reshape `[{…30 fields}]` into `[{ id, label }]` inside a `response:` block — bind the whole array.
+- **A tool's Zod `output` does not strip at runtime.** It only advertises the JSON Schema; the runtime returns your `fulfil` output verbatim, so `z.array(z.object({ id, label }))` will NOT drop extra element fields.
+- **So narrow in a compute connector.** To reshape each element, synthesize a `label`, or normalize a missing array to `[]`, pass the whole array to a `.compute(...)` op whose `run` maps it (a connector is HTTP **or** compute, not both — use a second connector). To only *drop* known fields without reshaping, `projection: { hiddenFields: [...] }` deletes them from each element. Worked example: `examples/weather` — `search_list` binds the array, then `geo_places.narrow` reshapes to `{ id, label }` and normalizes no-results to `[]`; `examples/sharepoint-lists` shows the same pattern against a real API.
+
+For a **paginated** API, collect across pages with a `pagination` config; the collected list is then `${response.items}`:
+
+```ts
+pagination: {
+  kind: 'cursor',                       // or 'pageNumber'
+  items: '${response.results}',         // the array on ONE page
+  nextCursor: '${response.next_cursor}', // 'pageNumber' uses hasMore + pageParam instead
+  cursorParam: 'cursor',
+  maxPages: 5, maxItems: 100,
+},
+// items / nextCursor / hasMore run over ONE raw page; your response mapping runs over the
+// collected aggregate, so the full list is:
+response: { tasks: '${response.items}' },
+```
+
+### Bound exceptional response sizes
+
+HTTP operations default to a 1 MiB decoded-response limit. Narrow the upstream query, paginate, or
+reduce the requested dataset before raising it; a `response` mapping runs only after the raw body is
+buffered. When representative evidence proves one operation legitimately needs more, grant only that
+operation the required bytes, up to the 6 MiB authoring maximum:
+
+```ts
+search: {
+  type: 'read', method: 'GET', path: '/search',
+  limits: { maxResponseBytes: 6 * 1024 * 1024 },
+  // input / output / response omitted
+},
+```
+
+The inclusive limit counts decoded streamed bytes. `response_too_large` is a safe structured reason;
+never copy a response body, header, URL, credential, or upstream error prose into user-visible output.
+
+### Create, update, delete
+
+Pair the read/list with the mutations your intent tools need:
+- **Create / update** — `method: 'POST'` / `'PATCH'`; author the body as `request: { field: '${input.x}' }` (do not nest it under `body`). It is JSON by default; use `requestEncoding: 'form-urlencoded'` only when the API requires a URLSearchParams body. URL query params remain the operation-level `query: [...]` array.
+- **Delete / close** — many endpoints return `204 No Content`. Set `responseType: 'empty'`, which enforces the status and binds `{}` (there is no body to map).
+
+```ts
+search_quotes: {
+  type: 'read', method: 'POST', path: '/quotes/search',
+  requestEncoding: 'form-urlencoded',
+  request: {
+    'from airport id': '${args.fromAirportId}',
+    'aircraft[categories]': '${args.categories}', // arrays become one JSON field
+  },
+  // input / output / response omitted
+},
+```
+
+`form-urlencoded` accepts a request object, not a pre-encoded string. Noodle preserves field order,
+omits `undefined`, stringifies primitive values, JSON-stringifies arrays/nested objects into one
+field each, and owns the exact `application/x-www-form-urlencoded;charset=UTF-8` content type.
+
+```ts
+close_task: {
+  type: 'action', method: 'POST', path: '/tasks/{id}/close',
+  input: z.object({ id: z.string() }),
+  responseType: 'empty',
+},
+```
+
+### Design intent tools
+
+Create intent-shaped tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
+find/search operation that returns `{ id, label }` summaries so the model resolves text → id itself,
+and map each response to a few labelled fields the model can speak from. See the "Design tools for the
+model" section of `references/authoring-workflow.md`.
+
+### Set the secret for local runs
+
+Local `dev`, smoke commands, secrets, and variables resolve one effective target: explicit flags, then the project link, then the saved CLI target, then local defaults. Set the secret through that same target:
+
+```sh
+# Canonical: writes to the effective local environment used by dev/test/devtools:
+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.
+
+Scoped local values live in `./.env.noodle`; the exact project-root `.env` is a read-only fallback for matching `secret("NAME")` / `variable("NAME")` declarations during local authoring. Never commit or print either file. Local authoring may read them only through this managed resolution path, and an interactive human `noodle deploy` may copy only missing declared `.env` names through its default-No import consent flow; agents and non-interactive runs use the value-free recovery commands instead. A required value that cannot resolve makes local commands stop before exposing an empty endpoint.
+
+### Prove real output
+
+`noodle validate` / `noodle test` prove a connector tool *compiles and registers* — not that its
+mapping returns data. With the secret set, run a live read: `noodle tools call <read_tool> --args
+'{…}'` executes the connector against the real API in-process. Confirm the mapped fields are populated,
+not `undefined`; if they are empty, distinguish a legitimate empty result from a missing or incorrect mapping, fix `${response…}` paths against the real payload when needed, and re-run.
+Only run a live write after explicit user approval and when a safe test target and expected effect are known.
+
+## Verification evidence
+
+- **Credential path:** the raw credential remained in an environment variable and the managed `secret(...)` path for the same effective local target.
+- **Observed shape:** a representative safe live read established the real fields, nesting, arrays, pagination, and empty-result behavior used by the mapping.
+- **Local proof:** `noodle validate --json` and `noodle test --json` succeeded, then `noodle tools call` returned populated mapped fields or an intentionally verified empty result.
+- **Writes:** name the approval and safe target used, or report writes as not run.
+- **Hosted boundary:** local proof does not prove hosted credentials, deployment health, or host behavior. Report hosted checks as not run unless a separate requested route exercised them.
+
+## Recovery paths
+
+- Authentication failure: verify the connector auth kind, managed secret name, and effective local target without printing the credential.
+- Successful HTTP call with `undefined` fields: compare the mapping with one sanitized observed response, correct the path, and rerun the same read.
+- Legitimate empty result: test a second known query or record the empty case as intentional; do not rewrite a correct mapping merely to manufacture data.
+- Response too broad for the model: narrow it with response mapping, projection, or a separate compute connector; do not rely on a Zod output to strip runtime fields.
+- Repeated external failure: stop after bounded attempts and report the sanitized status, endpoint class, evidence already proven, and exact external action needed.
+
+## Stop conditions
+
+- Stop complete when the representative safe read returns populated mapped fields or an intentionally verified empty result through the same effective local target.
+- Stop before a live write without explicit approval, a known effect, and a safe target.
+- Stop blocked when credentials, a reachable service, a representative input, or a required private schema is unavailable.
+- Do not continue into App design, deployment, or publication unless the user requested that next outcome; route to the corresponding primary playbook instead.

package/skills/claude-code/creating-product-agent-guides/SKILL.md

@@ -3,7 +3,7 @@ name: creating-product-agent-guides
 description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
 ---
 
-<!-- noodle-skill version:0.90.0 hash:0fa48a82fe836cf0 -->
+<!-- noodle-skill version:0.92.0 hash:0e06e11254563b6a -->
 
 # creating-product-agent-guides
 
@@ -27,7 +27,7 @@ Create or revise one grounded TypeScript product guide, prove it locally, and pr
 
 ## Workflow
 
-Read and follow the canonical playbook `references/product-agent-guides.md` at `../noodle-seed/references/product-agent-guides.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Read and follow the canonical playbook at `references/product-agent-guides.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
 
 ## Verification evidence
 

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

@@ -0,0 +1,55 @@
+# Product agent guides
+
+An `agentGuide` is the optional, host-neutral, TypeScript-only source for product-level workflow guidance beyond individual MCP capability descriptions. Noodle validates it and generates the App Package product skill; it does not invent the guide’s product judgment.
+
+## Required decision
+
+Do not wait for the user to name `agentGuide`. During every MCP server or App build, decide whether the product needs one and state the decision and reason in the design or handoff.
+
+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 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.
+
+A product with a single self-explanatory capability may omit the guide when its description, schema, and annotations fully communicate safe use and there is no product-specific workflow or boundary to add. Tool count is a signal, not a rule: one ambiguous or consequential capability can still require a guide, while several independent self-explanatory capabilities may not.
+
+Make the judgment from the user’s stated outcome and grounded product evidence. If a guide is warranted but a decision-changing workflow or boundary is unknown, ask only for that missing product input; never fabricate it. The user should not need to know this feature name to receive the benefit.
+
+## Scope boundaries
+
+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.
+
+Host-neutral distribution metadata, available target adapters, local exports, and deployment-bound archives are separate projections from the guide; use the live command catalog for exact target availability, and never claim that an export submitted or published itself. The deployed embedded assistant automatically consumes a compact authorization-aware guide projection. A direct external agent connected to the tenant MCP URL can discover the deployment skill through the modern draft MCP Skills extension when its host supports that extension; this is protocol delivery, not evidence of host support or marketplace installation.
+
+## Creation workflow
+
+1. **Inspect grounded capability evidence.** Read the configured TypeScript entrypoint (`server.ts` or `src/server.ts`) and identify its exact declared tools, resources, prompts, descriptions, visibility, annotations, authorization, and widget relationships. Treat schemas and compiled annotations as facts. Never invent or guess a tool, resource, prompt, capability kind, workflow, or weaker write boundary.
+2. **Decide guided or unguided.** Apply the criteria above and state the decision with its evidence. If the existing capabilities are self-explanatory and no product judgment is missing, recommend an intentionally unguided server and stop this workflow.
+3. **Interview only for product judgment.** Ask the builder for the decision-changing triggers, workflow ordering, grounding or clarification rules, boundaries, and representative prompts that source cannot prove. Do not ask them to restate capability names or schemas already present in TypeScript.
+4. **Propose TypeScript.** Present the complete proposed `agentGuide` block, map every step to one exact declared capability and kind, and call out how write, destructive, open-world, confirmation, authorization, and widget boundaries remain unchanged. Request explicit approval before editing the configured TypeScript entrypoint.
+5. **Apply and prove after approval.** Add or revise only the approved TypeScript guide. Run `noodle validate --json`, repair each structured guide error at its exact path without free-form invention, then run `noodle test --json`.
+6. **Preview the App Package plan.** Run `noodle agents setup --json` and report its exact target, file, ownership-migration, removal, and replacement actions. A preview never writes files. For an existing installed app skill, pass `--regenerate-app-skill` to state the intended operation explicitly; add `--replace-modified-app-skill` only when the builder is considering replacement of previously Noodle-owned bytes.
+7. **Ask separately before installation.** Request explicit approval before writing or replacing the app product skill. On approval, run `noodle agents setup --write` for a first installation, or `noodle agents setup --write --regenerate-app-skill` for a changed, migrated, renamed, or removed installation. Add `--replace-modified-app-skill` only when the preview identified modified previously owned bytes and the builder approved losing those exact local modifications.
+
+## Authoring shape
+
+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 concise global behavior that applies to every turn and caller. Put product workflow ordering, triggers, and workflow-specific permission guidance in `agentGuide`; global description, `useWhen`, and boundaries must be safe for every assistant surface. 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.
+
+For a deployed embedded assistant, Noodle automatically derives bounded server-side model guidance from that App Package. Each turn retains only complete workflows supported by the session surface and the exact model-visible tools allowed for the verified roles and scopes. All managed, React, headless, and public-client renderers benefit without a new browser option; raw guide and skill files never enter the browser response. An unavailable or oversize projection is omitted without widening tools or failing the turn.
+
+For a direct modern MCP connection, use the deployment tenant MCP URL and its existing OAuth flow; do not install a second skill or create another auth integration. `skills/list`, `skills/get`, and the related `resources/read` files are rebuilt from the same deployment package for the verified caller. Only complete workflows backed by currently authorized, model-visible tools and available resources or prompts survive; app-only helpers and forbidden tools stay out of both the workflow body and MCP-surface reference. The response is private with zero freshness, and each file has a caller-specific SHA-256 digest. A role or scope change can therefore change the next response and its digest, allowing a supporting host to require fresh approval. Legacy MCP clients and modern hosts without Skills support continue to use the ordinary capability surface.
+
+## Local lifecycle
+
+`noodle agents setup` previews the local product-skill files compiled from `server.ts`; add `--write` for the first installation under `.agents/skills/<app-skill>/` and `.claude/skills/<app-skill>/`. No account or hosted deployment is required. The app files have an ownership record separate from the Noodle workflow skills.
+
+A normal `noodle agents setup --write` refreshes Noodle-owned workflow skills but leaves an already installed app product skill unchanged. Regeneration, ownership-schema migration, rename, and removal require `--regenerate-app-skill` and are previewed even when `--write` is present without that flag. `--force` applies only to Noodle-owned project context and never overwrites a modified app-skill file. `--replace-modified-app-skill` is the narrower, separately approved recovery for previously owned app-skill bytes; it never claims unowned collisions or bypasses malformed state.
+
+Run `noodle agents doctor --json`: `agent_skill_modified` means preserve and review local bytes; `agent_skill_stale` means source, surface, renderer, installed files, or ownership schema changed, so preview explicit regeneration; `agent_skill_invalid_state` means the ownership record is malformed or unsafe, so preserve the files and review the record before retrying.
+
+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/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.90.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.92.0 hash:8d75ad13f4b3120a -->
 
 # debugging-mcp-delivery
 
@@ -27,9 +27,9 @@ Repair or isolate the first failing evidence layer while preserving everything a
 
 ## Workflow
 
-Read and follow the canonical playbook `references/verify-and-recover.md` at `../noodle-seed/references/verify-and-recover.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
-Load `references/troubleshooting.md` at `../noodle-seed/references/troubleshooting.md` only when the playbook or observed evidence names that concern.
-Load `references/inspect-hosted.md` at `../noodle-seed/references/inspect-hosted.md` only when the playbook or observed evidence names that concern.
+Read and follow the canonical playbook at `references/verify-and-recover.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load the supporting reference at `references/troubleshooting.md` only when the playbook or observed evidence names that concern.
+Load the supporting reference at `references/inspect-hosted.md` only when the playbook or observed evidence names that concern.
 
 ## Verification evidence
 

package/skills/claude-code/debugging-mcp-delivery/references/inspect-hosted.md

@@ -0,0 +1,26 @@
+# Inspect hosted state
+
+Read hosted evidence without changing target, credentials, configuration, access, host wiring, revisions, or directory state.
+
+## Use when
+
+- The user asks for hosted status, deployment metadata, health, logs, events, metrics, audit evidence, or diagnosis.
+- The request is inspect-only, diagnose-only, or asks whether an existing deployment works.
+
+## Authority boundary
+
+This route is read-only. It never authorizes `login`, `logout`, `link`, `target set`, hosted secret/variable/config/access changes, `deploy`, `rollback`, host configuration writes, or directory submission. If evidence shows one of those actions is needed, report the exact proposed action and target, then stop for a new explicit user request.
+
+## Workflow
+
+1. Resolve the requested org, app, environment, and deployment from existing non-secret context. Do not change the effective target to make inspection easier.
+2. Choose the narrowest read-only command: `noodle target show`, `noodle status`, `noodle inspect`, `noodle smoke`, `noodle metrics --agent-output`, `noodle events --json`, `noodle logs`, or `noodle audit`.
+3. Prefer machine output when the selected command supports it. Record the target, revision/deployment ID, timestamp, result, and any request ID without exposing secrets or customer payloads.
+4. When the installed Developer MCP is available, call `get_context` to read the signed-in user’s current organizations and roles. Resolve the intended organization from the request or project context, then pass that explicit `org` to every scoped inspection or diagnosis tool. Never infer a remote default, and never ask the user to preselect organizations during OAuth. Treat the connection as live evidence gathering, not mutation authority.
+5. If a command fails, distinguish missing authentication/access from unhealthy application behavior. Do not repair, relink, redeploy, rotate config, or roll back under this route.
+
+## Stop conditions
+
+- Stop complete when the requested hosted fact is supported by current evidence and higher untested levels are named.
+- Stop blocked when existing access cannot read the target or the requested evidence requires a host/user journey unavailable in scope.
+- Stop for authorization when the next useful action would mutate local targeting, hosted state, host configuration, or directory state.

package/skills/claude-code/debugging-mcp-delivery/references/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting in hosts
+
+## Contents
+
+- First moves
+- Customer-auth metadata
+- Symptom map
+
+## First moves
+
+Re-run the local gates before debugging in-host: `noodle validate`, `noodle check` (add `--target chatgpt` for ChatGPT-specific requirements), and `noodle doctor`. Confirm the CLI is current with `noodle update --check` and that the project-local skill is intact with `noodle agents doctor --json` — host metadata requirements evolve and fixes ship in the CLI/agent-kit. Never paste tokens, secrets, or `.env` / `.env.noodle` values into prompts or logs while debugging.
+
+For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `noodle` subcommand. Use it against a local `noodle dev` URL without an access token, or against hosted URLs through the host/OAuth flow printed by `noodle connect`.
+
+## Customer-auth metadata
+
+Adding `embeddedAssistant(...)` does not select the MCP access mode or authorization server. Before changing auth, inspect the exact active deployment with `noodle deployments list --org <org> --app <app> --env <env> --json` and match its active deployment ID, server version, and access mode to the endpoint being tested.
+
+For `customers` access, Direct or federated customer auth must advertise the configured tenant issuer; a managed Noodle bridge must advertise the Noodle authorization server. Owner-only access advertises the platform authorization server. If a direct or federated `customers` deployment still advertises the platform issuer, treat it as `customer_auth_state_inconsistent` and escalate with the endpoint, active deployment ID, and sanitized protected-resource metadata. Do not proxy, rewrite, rotate, or redeploy to hide the mismatch. Never share bearer tokens, refresh tokens, client secrets, or credential files.
+
+## Symptom map
+
+| Symptom | Likely cause | Fix |
+| :-- | :-- | :-- |
+| Images, fonts, or styles don’t load inside the widget | The host sandbox silently blocks origins not declared in the widget CSP | Add every asset origin to `csp: { resourceDomains: [...] }` (fetch/XHR origins go in `connectDomains`, embedded iframes in `frameDomains`), then re-run `noodle check --target chatgpt` |
+| ChatGPT warns “Widget CSP is not set” | The widget declares no `csp` | Declare `csp` on the widget with the exact origins it uses |
+| ChatGPT warns “Widget domain is not set” | No `domain` on the widget (required for app-store submission) | Set `domain: "https://…"` (one https origin per app) on each widget |
+| External links do nothing, or show a safe-link warning | Link opened outside the host bridge, or the target origin is not allowlisted | Use `useOpenExternal()` (never `window.open`) and add the target origins to the server-level `handoff.allowedDomains` |
+| Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `tool`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
+| Widget shows stale or missing data | The widget reads `structuredContent`, which must match the `output` schema | Make `fulfil` return exactly the `output` shape (arrays and nested objects are supported); inspect the live result with `noodle devtools` |
+| `useCallTool` fails from the widget | Tool name mismatch, or the helper tool is model-visible | List names with `noodle tools`; widget-only helpers must be declared with `tool` |
+| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Vite is missing from the app dependencies or its dependencies are not installed — widget bundling uses the app-local Vite | Run `npm install --save-dev vite`, then retry `noodle validate` / `noodle dev` / `noodle deploy` |
+| Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
+| Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
+| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (a `.body` segment, when the parsed body is bound directly to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
+| A connector should return a list but returns one item, `undefined`, or the whole raw objects | A `${response.arr[0]…}` mapping picks ONE element; a response mapping cannot reshape array items and a tool’s Zod output does not strip them at runtime | Bind the whole array with `${response.<arr>}`, then narrow each element in a compute connector (`references/connect-an-api.md` → “Return a list”) |
+| `noodle dev` boots but the loopback returns `-32600 "not found"` (or 404) for a valid server | A required `secret(...)` is unresolved — a missing secret fails compile *closed* at boot so nothing is served; the local secret was set at a scope `noodle dev` does not read | Run `noodle secrets set NAME --runtime local --from-env NAME`; local config and dev resolve the same effective target, and every author-loop command stops with the exact target/recovery command before exposing an empty endpoint (`references/connect-an-api.md` → “Set the secret for local runs”) |
+| Need to invoke a tool from the terminal | Local tools run in-process; the `noodle` CLI is not a general MCP client for **deployed** URLs (there is no `call <url>` verb) | Locally, `noodle tools call <name> --args <json>` (also `noodle resources read` / `noodle prompts get`) runs the tool against the in-process runtime — with the secret set it executes the connector against the real API, so use it to prove mapped output. For a **deployed** URL use MCP Inspector or `npx @mcpjam/cli@latest tools call --url <url> ...` |
+| One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |

package/skills/claude-code/debugging-mcp-delivery/references/verify-and-recover.md

@@ -0,0 +1,67 @@
+# Outcome
+
+Identify the first failing evidence layer, repair only that layer, rerun it, and report the highest level actually proven. A successful lower layer must never be presented as proof of a higher one.
+
+## Use when
+
+- The user asks to validate, test, diagnose, recover, or establish whether a local or hosted Noodle Seed project works.
+- A command, connector, App, host integration, deployment, or production check is failing or has uncertain evidence.
+
+## Do not use when
+
+- The primary request is to design or build a new product capability; select its build route and use this playbook only if evidence fails.
+- The user asks for a higher-risk external action rather than diagnosis. This route does not grant deployment, publication, live-write, or merge authority.
+
+## Required inputs
+
+Capture the requested evidence level, the exact command or user-visible symptom, sanitized machine output, the environment/target, and the last known passing layer. Do not broaden the goal beyond the level the user asked to prove.
+
+## Workflow
+
+Use this ordered evidence ladder. Start at the last known passing layer or the lowest plausible failure; never jump upward over an unproven dependency:
+
+1. **Compile** — the TypeScript build and authoring import surface are valid.
+2. **Validate** — `noodle validate --json` accepts the Noodle contract.
+3. **Local smoke** — `noodle test --json` starts the local runtime. Open apps exercise MCP registration; customer-auth apps must instead pass the anonymous 401 plus exact protected-resource metadata boundary and report `interactiveRequired: true`.
+4. **Customer auth** — when customer auth is declared, run `noodle auth doctor src/server.ts --json` for metadata and JWKS readiness, then run `noodle devtools src/server.ts`, complete sign-in, and make one authenticated `tools/list` request or representative safe read. The doctor does not prove that registration or token issuance succeeds; the authenticated request proves issuer, signature, stable audience, and exact-resource binding together.
+5. **Real API** — a representative safe `noodle tools call` proves connector credentials, transport, observed mapping, and populated data.
+6. **App compliance** — `noodle check --json` and local devtools prove the App contract and intended states.
+7. **Host** — the requested host connects, invokes the expected capability, and renders useful fallback/UI behavior.
+8. **Deploy** — the requested hosted revision and configuration exist and report healthy at the deployment layer.
+9. **Production health** — the live production endpoint and requested user journey are observed on the intended revision.
+
+For the first failing layer:
+
+1. Read the process exit code or status first. If machine JSON exists, parse it before reading human prose or editing files.
+2. For validation envelopes, inspect every `error.errors[]` item and repair the field at its reported `path`. Use `references/agent-contract.md` for the envelope and `references/compile-errors.md` for the named error code.
+3. Form one evidence-backed cause from the observed output. If the two canonical supports do not cover it, select one matching symptom from the router lookup catalog; do not scan every recovery path.
+4. Make the smallest in-scope repair. Do not freeform re-edit adjacent code, change credentials, redeploy, or add product behavior without evidence and authority.
+5. Rerun only the same evidence layer that failed. Once it passes, continue upward only to the user-requested level.
+6. Stop after two evidence-backed repair attempts with the same failure signature, or immediately when the next action requires new authority or external state.
+
+## Verification evidence
+
+Report a compact ledger for every exercised layer: command/action, target, result, and the evidence it establishes. Claim only the highest contiguous passing layer.
+
+- Compile success does not prove runtime behavior.
+- Validation and local smoke do not prove a real API mapping or credential path.
+- A protected-boundary smoke or passing auth doctor does not prove DCR, token issuance, token audience, or authenticated MCP access.
+- Local evidence does not prove hosted or host behavior.
+- Deployment existence does not prove production health or a user journey.
+- Report every requested but unperformed or blocked higher layer as not run, with the reason.
+
+## Recovery paths
+
+- Compile/validation: repair the exact import, schema, or reported path, then rerun that command without freeform changes.
+- Local boot/smoke: use the structured startup error to correct the effective target, config, or entrypoint before retrying.
+- Real API: distinguish authentication, reachability, legitimate empty results, and broken response mappings before changing code.
+- App: repair the cited contract or state in `noodle check --json`, then confirm it in devtools before attempting a host.
+- Host/deployment/production: confirm revision, target, identity, and configuration independently; do not infer one from another.
+- Repeated external failure: preserve passing evidence and report the sanitized failure, required authority or external state, owner, and exact next action.
+
+## Stop conditions
+
+- Stop complete when the user-requested evidence level and every dependency below it pass in the current target.
+- Stop blocked when progress requires credentials, approval, host access, deployment authority, production access, or an external-state change not available in scope.
+- Stop after two evidence-backed repair attempts with the same failure signature at one layer; do not hide repetition behind unrelated edits.
+- Never claim fixed or working without rerunning the failed layer, and never upgrade compile, local, deployment, or stale historical evidence into a stronger claim.

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.90.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.92.0 hash:3a1e14ff9b98ddbd -->
 
 # deploying-mcp-services
 
@@ -27,8 +27,8 @@ Apply only the explicitly authorized hosted mutation to the explicit org, app, a
 
 ## Workflow
 
-Read and follow the canonical playbook `references/deploy-and-ops.md` at `../noodle-seed/references/deploy-and-ops.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
-Load `references/cli-commands.md` at `../noodle-seed/references/cli-commands.md` only when the playbook or observed evidence names that concern.
+Read and follow the canonical playbook at `references/deploy-and-ops.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+Load the supporting reference at `references/cli-commands.md` only when the playbook or observed evidence names that concern.
 
 ## Verification evidence
 

package/skills/claude-code/deploying-mcp-services/references/cli-commands.md

@@ -0,0 +1,106 @@
+# noodle CLI commands
+
+Developer-facing `noodle` commands, grouped by area. Local authoring commands (`validate`, `test`, `dev`, `tools`, `resources`, `prompts`) need no login or link. Discover the exact command surface for the installed release with `noodle commands --json`.
+
+## Contents
+
+- Authoring & validation
+- Local run & inspect
+- Hosted deploy & operations
+- Org & members
+- Managed config
+- Governance & observability
+- CLI maintenance
+
+## Authoring & validation
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle start` | Guided first-run: sign in, scaffold, then deploy or run locally (`--json` for headless). |
+| `noodle init` | Create a local Noodle project. |
+| `noodle setup` | Reconcile project config and local agent files (dry-run unless `--write`). |
+| `noodle doctor` | Check login, service, project, validation, and config. |
+| `noodle agents` | Manage AI agent skills and project context (`setup`/`context`/`doctor`). |
+| `noodle auth` | Use `auth google` for keyless Google workload identity; diagnose downstream credentials without a business-tool call. |
+| `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 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. |
+
+## Local run & inspect
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle tools` | List local tools via a loopback MCP smoke. |
+| `noodle resources` | List local resources via a loopback MCP smoke. |
+| `noodle prompts` | List local prompts via a loopback MCP smoke. |
+| `noodle dev` | Run a local loopback runtime that serves + hot-reloads the manifest (no login). |
+| `noodle devtools` | Preview local widget metadata and rendering. |
+| `noodle design` | Inspects the latest finalized widget design brief (`inspect --latest --json`). |
+
+## Hosted deploy & operations
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle link` | Bind this directory to a Noodle Seed Cloud target (org/app/env). |
+| `noodle assistant` | Manage backend credentials for customer-branded embedded assistant clients. |
+| `noodle deploy` | Deploy the server to Noodle Seed Cloud. |
+| `noodle open` | Open or print the latest deployment URL. |
+| `noodle status` | Show hosted deployment status. |
+| `noodle inspect` | Inspect hosted deployment metadata without secret material. |
+| `noodle smoke` | Run hosted readiness diagnostics and print external smoke commands. |
+| `noodle rollback` | Roll back to a previous deployment. |
+| `noodle archive` | Archive the whole app: endpoints answer 410 Gone; hard-deleted after the retention window. |
+| `noodle restore` | Restore an archived app within the retention window. |
+| `noodle access` | Set the access mode (owner-only\|org-members\|authenticated\|customers). |
+| `noodle apps` | List or inspect hosted apps for an org (`apps list`/`apps inspect <app>`). |
+| `noodle envs` | List or inspect environments for an app (`envs list`/`envs inspect <env>`). |
+| `noodle deployments` | List or inspect individual deployments (`deployments list`/`deployments inspect <id>`). |
+| `noodle distributions` | Publish immutable host archives, record their lifecycle, and operate bounded delivery. |
+| `noodle service` | Query hosted service capabilities. |
+| `noodle login` | Authenticate with Noodle Seed Cloud. |
+| `noodle logout` | Clear saved credentials. |
+| `noodle whoami` | Print the current authenticated user. |
+| `noodle feedback` | Send sanitized product feedback (bug, idea, docs gap) to the Noodle Seed team. |
+| `noodle github` | Connect, inspect, or disconnect the GitHub repository behind an app’s GitHub-native deploys (`connect`/`status`/`disconnect`; `connect` opens a browser install, `--repo` for headless). |
+| `noodle target` | Show or set the deployment target (local\|cloud\|other). |
+
+## Org & members
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle orgs` | List or create orgs. |
+| `noodle members` | Manage org members (list/add/remove). |
+
+## Managed config
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle secrets` | Manage managed secrets (set/list/delete/resolve) by org/app/env scope. |
+| `noodle variables` | Manage managed variables (set/list/delete/resolve) by org/app/env scope. |
+
+## Governance & observability
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle audit` | Operator governance audit status and event queries. |
+| `noodle knowledge` | Operator-only knowledge components: list, status, and refresh (ADR 0202). |
+| `noodle logs` | View service/deployment logs. |
+| `noodle metrics` | MCP analytics for a deployed server (volume, sessions, latency percentiles, two-tier errors, tools, clients). Agents: `noodle metrics --agent-output` for a health verdict + next actions. |
+| `noodle events` | The per-request MCP event stream with status/tool/client filters; `--session <id>` replays one session in order. Agents: add `--json` and filter (`--status tool_error\|mcp_error`) when debugging. |
+| `noodle alerts` | Analytics alert rules (`add\|list\|remove\|test`): an edge-triggered webhook fires when error share, error count, calls, or p95 latency breaches. Webhook URLs are stored server-side and shown redacted. |
+| `noodle intents` | Operate optional environment-scoped intent capture (`status\|enable\|disable\|list\|purge`); model participation is best-effort and purge is irreversible. |
+| `noodle policy` | Manage policy (status/list/show/effective/simulate/suspend/quota/rate/...). |
+
+## CLI maintenance
+
+| Command | What it does |
+| :-- | :-- |
+| `noodle help` | Print CLI usage and command help. |
+| `noodle version` | Print the installed CLI version. |
+| `noodle commands` | Print the machine-readable command catalog (`--json`) or a compact human list. Agents: `noodle commands --json` for every command, subcommand, flag, and exit code without reading source. |
+| `noodle features` | Print the versioned Claude, ChatGPT, and Embedded compatibility registry (`--json` or `--markdown`). |
+| `noodle update` | Check for, install, or safely repair the CLI update. Agents: `noodle update --check --json`, then `noodle update --yes --json`; add `--repair` only when the check reports `repairSafe: true`. |