@noodleseed/agent-kit 0.34.0 → 0.35.0

package/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "0.34.0",
+  "packageVersion": "0.35.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "6b00524e90bc7ddc31e615ff1ebb90836aead8503ed711bbd3fab45e9ac115fc",
+      "sha256": "bc487708c97735979ce2179f27e82988233819b2264cbe53c69320dbc2630800",
       "agentTarget": "codex"
     },
     {
@@ -26,6 +26,11 @@
       "sha256": "1c9c3e58f1263838484d033ef9aa4a0efd6a1696091fd5c1b41686e1b87ac41a",
       "agentTarget": "codex"
     },
+    {
+      "path": "skills/codex/references/build-an-mcp-server.md",
+      "sha256": "05dfa0df90e21a6a403806883e326caefb2dd5acec1c762b891b6e778327fd48",
+      "agentTarget": "codex"
+    },
     {
       "path": "skills/codex/references/authoring-workflow.md",
       "sha256": "5e64b735675bacdff9e893c03c6a30751844325854540e8952a1092cf57b1b98",
@@ -38,12 +43,17 @@
     },
     {
       "path": "skills/codex/references/connect-an-api.md",
-      "sha256": "b2ab03691502794d0e8b328d81a906636c9a65623abeddd51ce9658a4542fc4b",
+      "sha256": "c267092dc35141adeeddba6e5af4ebff71df2640cbb7b4c2e3b902d2b33a03ae",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/build-an-mcp-app.md",
+      "sha256": "71b80632a2f87b63849ff44a86ce03f883aaedf2c52441ea1030f343c160dbd3",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/experience-design.md",
-      "sha256": "40c5d7081f4c81cca5a7a2cfabe2e0fa8818eaabfd0214539765b70b6750d3cb",
+      "sha256": "dff779f01ff24984e1d24459620b2c9807bcfdb98ba8cb29f7467c7eb529ea30",
       "agentTarget": "codex"
     },
     {
@@ -56,24 +66,34 @@
       "sha256": "08e44784a0d838c322d443eae6b35d5c75b4252a0975db835ef504535e25584a",
       "agentTarget": "codex"
     },
+    {
+      "path": "skills/codex/references/verify-and-recover.md",
+      "sha256": "22b6a93faa0e20dc874ced541f2d453716892035a36e4278353c1b4150537fe3",
+      "agentTarget": "codex"
+    },
     {
       "path": "skills/codex/references/troubleshooting.md",
       "sha256": "238a8d0f4ff8635ed8b0bc63db734634c44ba82e78a3851dc50c85486e1fb942",
       "agentTarget": "codex"
     },
+    {
+      "path": "skills/codex/references/inspect-hosted.md",
+      "sha256": "944ea95b9e9e65c7ff9027b47bbc0c21ca1a81806d4126774cf869eb4b206b93",
+      "agentTarget": "codex"
+    },
     {
       "path": "skills/codex/references/deploy-and-ops.md",
-      "sha256": "d7e69158ba8e2b92cccea183c55cb42b1be091516a5a4ea9af94c900d285aa15",
+      "sha256": "1f74050942433f8f6a163243bc5a631c286c27612834739798798445e392ea92",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/publishing.md",
-      "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
+      "sha256": "b8e2ef715b51f70154e1210086cccb9e7165d95cd40a374546482679f355cff8",
       "agentTarget": "codex"
     },
     {
-      "path": "skills/codex/references/chatgpt-compliance.md",
-      "sha256": "b0d70446be90a3e76396207ff32e7dc9561f25f43fc313d80cc9d9afc12e9b99",
+      "path": "skills/codex/references/app-directory-compliance.md",
+      "sha256": "77a30c9af09c05502c2245795d49e3487a6b1b0c7a70e26aa0996b7d670dfce8",
       "agentTarget": "codex"
     },
     {
@@ -88,7 +108,7 @@
     },
     {
       "path": "skills/codex/examples/acme-bistro/README.md",
-      "sha256": "2bcf803ea2407479ddc70644a79ad503335880fd8439ed673b17c8d50e7cb59f",
+      "sha256": "b364c7db64afad1788ad321681f7e41bcc5f1c328829adeb12c78601d1522fbb",
       "agentTarget": "codex"
     },
     {
@@ -383,7 +403,7 @@
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "fe1c89cb5087de6dd67a02754a7b7553d42c26501b795ec243659e66c0585c7d",
+      "sha256": "bc487708c97735979ce2179f27e82988233819b2264cbe53c69320dbc2630800",
       "agentTarget": "claude-code"
     },
     {
@@ -406,6 +426,11 @@
       "sha256": "1c9c3e58f1263838484d033ef9aa4a0efd6a1696091fd5c1b41686e1b87ac41a",
       "agentTarget": "claude-code"
     },
+    {
+      "path": "skills/claude-code/references/build-an-mcp-server.md",
+      "sha256": "05dfa0df90e21a6a403806883e326caefb2dd5acec1c762b891b6e778327fd48",
+      "agentTarget": "claude-code"
+    },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
       "sha256": "5e64b735675bacdff9e893c03c6a30751844325854540e8952a1092cf57b1b98",
@@ -418,12 +443,17 @@
     },
     {
       "path": "skills/claude-code/references/connect-an-api.md",
-      "sha256": "b2ab03691502794d0e8b328d81a906636c9a65623abeddd51ce9658a4542fc4b",
+      "sha256": "c267092dc35141adeeddba6e5af4ebff71df2640cbb7b4c2e3b902d2b33a03ae",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/build-an-mcp-app.md",
+      "sha256": "71b80632a2f87b63849ff44a86ce03f883aaedf2c52441ea1030f343c160dbd3",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/experience-design.md",
-      "sha256": "40c5d7081f4c81cca5a7a2cfabe2e0fa8818eaabfd0214539765b70b6750d3cb",
+      "sha256": "dff779f01ff24984e1d24459620b2c9807bcfdb98ba8cb29f7467c7eb529ea30",
       "agentTarget": "claude-code"
     },
     {
@@ -436,24 +466,34 @@
       "sha256": "08e44784a0d838c322d443eae6b35d5c75b4252a0975db835ef504535e25584a",
       "agentTarget": "claude-code"
     },
+    {
+      "path": "skills/claude-code/references/verify-and-recover.md",
+      "sha256": "22b6a93faa0e20dc874ced541f2d453716892035a36e4278353c1b4150537fe3",
+      "agentTarget": "claude-code"
+    },
     {
       "path": "skills/claude-code/references/troubleshooting.md",
       "sha256": "238a8d0f4ff8635ed8b0bc63db734634c44ba82e78a3851dc50c85486e1fb942",
       "agentTarget": "claude-code"
     },
+    {
+      "path": "skills/claude-code/references/inspect-hosted.md",
+      "sha256": "944ea95b9e9e65c7ff9027b47bbc0c21ca1a81806d4126774cf869eb4b206b93",
+      "agentTarget": "claude-code"
+    },
     {
       "path": "skills/claude-code/references/deploy-and-ops.md",
-      "sha256": "d7e69158ba8e2b92cccea183c55cb42b1be091516a5a4ea9af94c900d285aa15",
+      "sha256": "1f74050942433f8f6a163243bc5a631c286c27612834739798798445e392ea92",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/publishing.md",
-      "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
+      "sha256": "b8e2ef715b51f70154e1210086cccb9e7165d95cd40a374546482679f355cff8",
       "agentTarget": "claude-code"
     },
     {
-      "path": "skills/claude-code/references/chatgpt-compliance.md",
-      "sha256": "b0d70446be90a3e76396207ff32e7dc9561f25f43fc313d80cc9d9afc12e9b99",
+      "path": "skills/claude-code/references/app-directory-compliance.md",
+      "sha256": "77a30c9af09c05502c2245795d49e3487a6b1b0c7a70e26aa0996b7d670dfce8",
       "agentTarget": "claude-code"
     },
     {
@@ -468,7 +508,7 @@
     },
     {
       "path": "skills/claude-code/examples/acme-bistro/README.md",
-      "sha256": "2bcf803ea2407479ddc70644a79ad503335880fd8439ed673b17c8d50e7cb59f",
+      "sha256": "b364c7db64afad1788ad321681f7e41bcc5f1c328829adeb12c78601d1522fbb",
       "agentTarget": "claude-code"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.34.0",
+  "version": "0.35.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,55 +3,73 @@ 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.34.0 hash:a26379cb2c3369a6 -->
+<!-- noodle-skill version:0.35.0 hash:75dd0f6f85b04858 -->
 
 # Noodle Seed
 
 Build, validate, test, deploy, and operate Noodle Seed MCP servers and apps authored in TypeScript with the `noodle` CLI. Author from the configured entrypoint (usually `server.ts`); keep the authoring surface TypeScript-only.
 
-Use this skill for project-local Noodle Seed authoring in Claude Code; preserve generated/user instruction boundaries.
+Use this skill for project-local Noodle Seed authoring in the active coding host; preserve generated and user instruction boundaries.
+
+If the request is unrelated to the Noodle MCP surface, stop here: follow the project's normal instructions and run no Noodle lifecycle commands.
 
 **Installed-plugin execution.** When this skill is supplied by the Noodle Developer plugin, preserve the managed invocation path established by the plugin bootstrap and invoke every `noodle` command through that host bundle's managed launcher. Do not install or update a global CLI. Noodle guides and operates the lifecycle; you write and test the application source in the user's project.
 
-## Golden path
+## Route the request
+
+Choose exactly one primary route from the user outcome below. Read that primary reference in full, then begin the work. Read supporting references only when the primary workflow sends you there or the named evidence exposes that concern. Stop discovery once the route is selected.
+
+Apply this precedence when wording overlaps: diagnosis of an existing failure takes the verification route; an MCP App/UI outcome takes the App route; external API integration from credentials, a URL, or an API specification takes precedence over generic server building; hosted inspection is the read-only route; hosted mutation requires the explicitly requested deployment route.
+
+Negative routing examples: “Inspect hosted logs/status” → `inspect-hosted` (read-only). “Prepare for deployment” → the applicable build or verification route and stop with a handoff; preparation does not authorize `link`, hosted config, deployment, rollback, host writes, or submission. “Keep this local” → a build or verification route, never a hosted route.
 
-This CLI is agent-native: the cold-agent-path commands speak the `--json` envelope (hosted admin/ops commands are still being normalized). Drive the loop by parsing machine state, not human prose. The full envelope, exit codes, and output modes are in `references/agent-contract.md`.
+| User outcome | Primary reference | Supporting references only when needed | Done when |
+| :--- | :--- | :--- | :--- |
+| Create or extend a headless MCP server whose external API contract is already modeled | `references/build-an-mcp-server.md` | `references/authoring-workflow.md`, `references/sdk-surface.md` | The requested server behavior is locally validated and tested; connector reads have real-output evidence. |
+| Connect a real API when credentials or an API specification are available | `references/connect-an-api.md` | `references/authoring-workflow.md` | A representative live read returns populated, intentionally mapped fields without exposing credentials. |
+| Build or change an MCP App, widget, or host-visible UI | `references/build-an-mcp-app.md` | `references/experience-design.md`, `references/widgets-and-apps.md` | The UI has a stated user benefit, passes the requested checks, and degrades to useful text. |
+| Validate, test, diagnose, or recover a failing local or hosted project | `references/verify-and-recover.md` | `references/agent-contract.md`, `references/compile-errors.md` | The failing evidence layer is repaired and rerun, or the remaining blocker and exact next action are reported. |
+| Inspect or diagnose hosted status, logs, metrics, events, or deployment metadata read-only | `references/inspect-hosted.md` | None | The requested hosted evidence is reported without changing target, configuration, access, or deployment state. |
+| Deploy, configure, connect with writes, change access, or roll back a hosted MCP service when explicitly requested | `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 | `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 | `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 | `references/feedback.md` | None | A sanitized command is shown to the user and is submitted only after explicit approval. |
 
-**Discover the skill first.** Before authoring anything, read this whole `SKILL.md` and scan the `## References` index below (including `references/examples.md`) so you build from the shipped patterns — connectors that return live lists, secret scoping, widgets, testing — instead of rediscovering them. Open the references your task touches in full.
+## Common machine loop
 
-Before authoring, design the experience — the funnel/handoff boundary, tools, widgets, display modes, and grounding — see `references/experience-design.md`. Then run the loop:
+The cold-agent commands speak the `--json` envelope. Parse machine state instead of scraping human prose; `references/agent-contract.md` owns the envelope and exit codes.
 
-1. **Discover** — `noodle commands --json`: every command, subcommand, flag, and exit code (don't read source).
-2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
-3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
-4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
-5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
-6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret on the same effective local target with `noodle secrets set <NAME> --runtime local --from-env <ENV>` (see `references/connect-an-api.md`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
-7. **Apps/widgets/embed** — `noodle check --json` (add `--target chatgpt|claude|embedded-assistant`), then `noodle devtools`; use `references/widgets-and-apps.md` for MCP Apps and `references/embedded-assistant.md` for a SaaS embed.
-8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
-9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
-10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
+1. **Discover** — use `noodle commands --json` when the required command or flags are uncertain; don't read CLI source.
+2. **Author** — for build routes, edit the configured TypeScript entrypoint, usually `src/server.ts`.
+3. **Validate** — run `noodle validate --json`; repair each `error.errors[]` item at its `path`, then re-run `noodle validate --json`.
+4. **Smoke** — run `noodle test --json` after validation passes.
+5. **Prove the requested level** — connector routes require a safe live read with `noodle tools call`; App routes require `noodle check --json` and `noodle devtools`; hosted or host actions run only when the selected route and current user request authorize that exact level.
+6. **Report evidence** — claim only the highest level actually exercised and name anything not run.
 
-## References
+## Reference lookup catalog
 
-Scan all of these during discovery; open in full the ones your task touches:
+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/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.
-- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the fit check, the validate→test→dev repair loop, connectors, and secrets/variables.
-- `references/embedded-assistant.md` — HTTPS origins, managed model config, deploy-before-client sequencing, backend session exchange, browser mounting, and credential boundaries.
-- `references/connect-an-api.md` — given an API key: secure it, probe the live API to learn the real shape, model the connector, and prove real output before building.
-- `references/experience-design.md` — design the app experience before authoring: funnel/handoff boundary, grounding, two-users, display modes, and the wireframe/UX spec.
-- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, the widget hook surface, output shaping, and CSP.
-- `references/test-in-hosts.md` — connect and test in ChatGPT (developer mode), Claude, agent hosts, and MCP Inspector.
-- `references/troubleshooting.md` — runtime symptom → cause → fix, in-host and hosted.
-- `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
-- `references/publishing.md` — submit to the ChatGPT apps directory and Claude connectors directory.
-- `references/chatgpt-compliance.md` — the OpenAI Apps SDK pre-submission checklist (beyond the metadata gate): conversational value, helpful-UI-only, in-chat completion, UI guidelines, domain guardrails, privacy.
+- `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/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.
+- `references/experience-design.md` — design an app experience: funnel boundary, grounding, two users, display modes, and wireframe.
+- `references/widgets-and-apps.md` — MCP Apps, typed views, widget hooks, output shaping, and CSP.
+- `references/test-in-hosts.md` — connect and test in real MCP hosts and protocol inspection clients.
+- `references/verify-and-recover.md` — ordered evidence ladder, bounded repair, and honest completion claims.
+- `references/troubleshooting.md` — runtime symptom to cause and fix, locally and hosted.
+- `references/inspect-hosted.md` — read-only hosted status, logs, metrics, events, and deployment diagnosis.
+- `references/deploy-and-ops.md` — explicitly authorized hosted link, config, deploy, access, connection writes, and rollback.
+- `references/publishing.md` — prepare and submit to app and connector directories.
+- `references/app-directory-compliance.md` — the pre-submission experience and policy checklist.
 - `references/examples.md` — flagship example index and a canonical `server.ts`.
-- `references/feedback.md` — draft sanitized product feedback, show the user the exact command, and submit only after explicit user approval.
+- `references/feedback.md` — draft sanitized product feedback and submit only with user approval.
 
 ## Product feedback
 
@@ -62,6 +80,7 @@ When you discover a bug, missing capability, misleading doc, or improvement idea
 - Keep secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle` values, and `~/.noodle/config.json` out of prompts, logs, docs, tests, and generated files.
 - Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata.
 - Do not add static data-plane credential paths; hosted access is identity-based.
+- Hosted mutation is opt-in. Run `link`, hosted secret/variable/config/access changes, deploy, rollback, host configuration writes, or directory submission only when the current user request explicitly authorizes the exact mutation and target. An inspect, prepare, validate, test, or local-only request grants no such authority; stop and ask before crossing that boundary.
 
 ## Customization
 

package/skills/claude-code/examples/acme-bistro/README.md

@@ -9,7 +9,7 @@ the app). It pairs a view-backed `tool` menu/cart with app-only `tool` cart help
 Capability slot: **end-to-end in-chat transaction + payment-only handoff**, plus a worked **design-first**
 deliverable set (`design/` — a UX Document, a single-file HTML wireframe with an embedded OpenAI Apps SDK
 compliance audit, and a Recommended API contract). It sets the quality bar the `noodle-seed` skill's
-`references/experience-design.md` and `references/chatgpt-compliance.md` teach. (Distinct from
+`references/experience-design.md` and `references/app-directory-compliance.md` teach. (Distinct from
 `food-ordering`, which is the broad widget-composition proof; this one owns the design-first end-to-end +
 compliance exemplar.)
 

package/skills/claude-code/references/app-directory-compliance.md

@@ -0,0 +1,59 @@
+# App directory compliance (pre-submission)
+
+Use this shared checklist against the built integration before preparing a directory submission. It
+covers evidence common to app and connector directories without assuming a particular host, review
+portal, client framework, or vendor policy.
+
+## Contents
+
+- Validation evidence
+- Capability and interaction quality
+- Safety, privacy, and data handling
+- Reliability and accessibility
+- Directory-specific delta
+
+## Validation evidence
+
+A clean local validation result proves only the checks that actually ran. Record server validation,
+behavior tests, protocol conformance, production reachability, and interactive rendering as separate
+evidence levels. Never treat metadata readiness as proof of host rendering or directory acceptance.
+
+## Capability and interaction quality
+
+1. **User value** — each exposed capability solves a concrete user job and cites built behavior rather
+   than an aspiration.
+2. **Grounded capability** — knowledge, actions, and presentation come from authoritative application
+   data or bounded operations instead of invented state.
+3. **Atomic interfaces** — every action has a focused purpose, explicit input and output schemas, honest
+   effect annotations, and useful failure output.
+4. **Helpful UI only** — every interactive surface earns its place and preserves a useful text or
+   structured fallback when rendering is unavailable.
+5. **Meaningful completion** — the user can complete the promised task within the declared boundary,
+   with any external handoff clearly identified.
+
+## Safety, privacy, and data handling
+
+- Minimize model-visible and UI-visible data; remove secrets, internal identifiers, unnecessary personal
+  data, and continuation credentials from results and logs.
+- Document authentication, authorization scopes, retention, deletion, subprocessors, and external
+  handoffs accurately in the public privacy and support material.
+- Make mutations explicit, bounded, and confirmation-aware. Never imply that a read or preparation
+  request authorizes a write.
+- For regulated or consequential workflows, show source provenance, uncertainty, cautions, and the
+  boundary between information and a professional decision.
+
+## Reliability and accessibility
+
+- Exercise representative positive, negative, empty, loading, error, and recovery cases against the
+  production-shaped endpoint.
+- Preserve keyboard access, readable contrast, responsive layout, concise status feedback, and graceful
+  degradation when an interactive surface is unsupported.
+- State latency, availability, rate-limit, and support expectations using observed evidence rather than
+  unverified claims.
+
+## Directory-specific delta
+
+After the shared checklist passes, read the selected directory’s current official documentation and add
+only its verified requirements. Keep directory-specific metadata, screenshots, test accounts, policy
+statements, and review procedures in that submission evidence—not in this shared skill reference. Mark
+unknown or untested requirements explicitly, and never reuse another directory’s checklist as a proxy.

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

@@ -0,0 +1,52 @@
+# Outcome
+
+Deliver an MCP App whose visual interaction gives the user a concrete benefit beyond a good text response, while preserving useful model-visible output when the widget is unavailable.
+
+## Use when
+
+- The user asks for an MCP App, widget, interactive card, visual workflow, or host-visible UI.
+- Comparison, selection, progress, editing, confirmation, or another visual interaction materially improves the conversational job.
+
+## Do not use when
+
+- A concise text or structured tool result fully serves the user. UI must earn its place.
+- The requested task is a headless server, API connector, diagnosis, deployment, or publication with no UI change; select that route.
+- The agent lacks the product inputs needed to explain who benefits, what action the UI enables, and what happens without it.
+
+## Required inputs
+
+Before implementation, capture a short design spec: target user, conversational job, explicit user benefit, information hierarchy, primary interaction, states (loading/empty/error/success), model-visible result, widget-only data, and useful text fallback. Use `references/experience-design.md` for the deeper product-design questions only when needed.
+
+## Workflow
+
+1. **Pass the UI fit check.** State why a visual interaction is better than text for this request. If there is no defensible user benefit, keep the capability headless and stop the App route.
+2. **Agree on the design spec.** Describe the smallest complete experience and its states before writing the component. Avoid recreating a full dashboard or website inside the conversation.
+3. **Define the output boundary.** Keep concise facts and action results model-visible. Put presentation-heavy or interactive widget data in the widget-only channel. The model must not depend on opaque UI state to continue the conversation.
+4. **Preserve fallback.** Every tool that launches a widget must still return useful text without the widget, so unsupported hosts and failed rendering remain usable.
+5. **Author and wire the App contract.** Follow `references/widgets-and-apps.md` for the canonical component guidance, view registration, hooks, state, CSP, tool visibility, and output shaping. Keep tool effects and confirmation semantics correct independently of the UI.
+6. **Validate the local artifact.** Run `noodle validate --json`, `noodle test --json`, and `noodle check --json`. Repair failures at the layer that produced them.
+7. **Inspect the experience.** Run `noodle devtools` and verify loading, empty, error, success, responsive layout, focus/keyboard behavior, and the text fallback.
+8. **Escalate evidence only on request.** Run a host test only when the user requested host verification. Run host-specific compliance only when preparing that host submission; select the exact host-testing or compliance entry from the router lookup catalog only after that evidence level is explicitly requested.
+
+## Verification evidence
+
+- **Product:** the design spec states the user benefit and the UI fit decision.
+- **Server:** `noodle validate --json` and `noodle test --json` succeeded.
+- **App contract:** `noodle check --json` succeeded.
+- **Local UX:** `noodle devtools` exercised the relevant states and the useful text fallback without the widget.
+- **Host/compliance:** report each requested host or compliance check with its evidence; report every unperformed higher level as not run.
+
+## Recovery paths
+
+- Weak UI fit: remove the widget and ship the stronger headless result, or narrow the visual interaction to the one decision it improves.
+- App check failure: repair the cited view, metadata, output, CSP, or accessibility issue and rerun `noodle check --json` before reopening devtools.
+- Blank or stale widget: verify the tool returns the intended widget data, the view is registered, and state derives from supported hooks rather than hidden global state.
+- Model cannot continue without UI: move the essential facts into model-visible output and keep only presentation data widget-only.
+- Host-only mismatch: record local checks as passed, isolate the host symptom, and select the host-testing lookup only for that observed host; do not rewrite a working local contract without host evidence.
+
+## Stop conditions
+
+- Stop complete at the locally requested boundary when product fit, server tests, App checks, devtools states, and text fallback are evidenced.
+- Stop before host connection, deployment, or submission unless the user requested that next evidence level.
+- Stop blocked when the required design decision, external data, credentials, or host access is unavailable; name the missing input and the exact next action.
+- Never claim host compatibility, directory compliance, or production behavior from local devtools evidence alone.

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

@@ -0,0 +1,54 @@
+# Outcome
+
+Deliver the smallest useful Noodle Seed MCP server that turns a real user intent into a safe, typed result. Author only the configured TypeScript entrypoint, normally `src/server.ts`; keep the public authoring surface TypeScript-only and never hand-author generated manifests or connector IR.
+
+## Use when
+
+- The user asks to create or extend a headless MCP server, tools, resources, prompts, or connector-backed behavior.
+- The requested result is primarily model-facing and does not require a widget or host-visible UI.
+
+## Do not use when
+
+- The primary outcome is an MCP App, widget, or visual interaction; select the App route.
+- The task is only to diagnose existing failures, deploy, publish, embed, or report feedback; select that dedicated route.
+- The idea has no conversational fit: static content, a dashboard, deep navigation, or a full existing app port should be narrowed to the few actions that are better said than clicked.
+
+## Required inputs
+
+Establish only the inputs needed for the requested stopping point. Follow `references/authoring-workflow.md` for the canonical discovery paths. Do not guess or invent a private schema, endpoint, authentication model, eligibility rule, or approval flow. If a required input is unavailable, state exactly what evidence is missing and stop before fabricating behavior.
+
+## Workflow
+
+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.
+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.
+8. **Stop at the requested boundary.** Do not add an App, host test, hosted environment, publication work, or deployment unless the user requested that outcome. Deploy only when the selected route or the user explicitly requires it.
+
+## Verification evidence
+
+Report evidence as a ladder and claim only levels actually exercised:
+
+- **Authoring:** the requested TypeScript behavior exists with typed inputs and outputs.
+- **Compilation:** `noodle validate --json` returned success.
+- **Local smoke:** `noodle test --json` returned success.
+- **Connector reality:** a representative safe read via `noodle tools call` returned populated mapped fields. This is required for connector-backed work.
+- **Higher levels:** explicitly report host, deployment, and production checks as not run unless they were separately requested and evidenced.
+
+## Recovery paths
+
+- Validation failure: fix each structured error at its reported path, rerun validation, then resume at the next unproven layer.
+- Tool registers but returns empty or `undefined` fields: inspect one sanitized real response, correct `${response...}` mappings, and rerun the same read.
+- Credential unavailable: verify `secret(...)` naming and the effective local target; never inline or print the secret.
+- Missing product input: ask for the smallest concrete example, schema, or rule that unblocks the selected job. Do not widen the build to compensate.
+- Repeated failure at the same layer: stop after two evidence-backed repair attempts with the same failure signature and report the command, sanitized error, evidence already proven, and exact next action.
+
+## Stop conditions
+
+- Stop complete when the requested behavior passes validation and local smoke, and every connector-backed read has real-output evidence.
+- Stop at the user's requested boundary; do not deploy unless the user requested deployment.
+- Stop blocked when progress requires unavailable credentials, private schemas, external approval, or a live write the user has not approved.
+- In the handoff, name what changed, what passed, what was not run, and any remaining risk without upgrading local evidence into a hosted or production claim.