@noodleseed/agent-kit 0.33.0 → 0.35.0

package/skills/codex/SKILL.md

@@ -1,67 +1,86 @@
 ---
 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.
-version: 0.33.0
-hash: 7228bf705097483b
 ---
 
+<!-- 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 local Noodle Seed project work in Codex.
+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` — send sanitized product feedback to the Noodle Seed team with `noodle feedback`, proactively, whenever you discover a bug, gap, or improvement.
+- `references/feedback.md` — draft sanitized product feedback and submit only with user approval.
 
 ## Product feedback
 
-When you discover a bug, missing capability, misleading doc, or improvement idea in the CLI, SDK, or any part of Noodle Seed, send it in the moment with `noodle feedback` — sanitized per `references/feedback.md` (never customer code, secrets, or personal data), one submission per finding.
+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.
 
 ## Safety
 
 - 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/codex/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/codex/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/codex/references/authoring-workflow.md

@@ -233,7 +233,7 @@ The model never sees a task id from the user; `find_tasks` returns `{ id, title
 
 ## Invocation context
 
-Every executable invocation receives one immutable server-authoritative temporal snapshot. Canonical TypeScript authoring emits Core v2 and does not create a hidden context tool. Use `server(..., { context })` for locale/time-zone defaults and trusted ambient facts, and designate one normal zero-input tool with `contextProvider: true` when the model needs portable application context. The embedded host preloads it per turn; Claude, ChatGPT, and other MCP hosts call it normally.
+Every executable invocation receives one immutable server-authoritative temporal snapshot. TypeScript authoring does not create a hidden context tool. Use `server(..., { context })` for locale/time-zone defaults and trusted ambient facts, and designate one normal zero-input tool with `contextProvider: true` when the model needs portable application context. The embedded host preloads it per turn; Claude, ChatGPT, and other MCP hosts call it normally.
 
 ```ts
 context: {
@@ -251,7 +251,7 @@ context: {
 },
 ```
 
-Ambient providers are recorded as fulfilment data at author time, may call read-only connector operations only, and have a declared output schema. Later fulfilments read `${context.temporal.localDate}`, `${context.temporal.timeZone}`, `${context.ambient.defaultTeamId}`, and `${context.ambientStatus}`. If ambient resolution fails, the status is `unavailable`; never invent the missing business facts. Core-v1 `server.context` keeps the reserved `noodle_context` adapter; Core v2 never reserves it. Ambient/model-visible context is capped at 16 KiB serialized JSON, depth 8, and 128 entries per container; credential-shaped keys are rejected.
+Ambient providers are recorded as fulfilment data at author time, may call read-only connector operations only, and have a declared output schema. Later fulfilments read `${context.temporal.localDate}`, `${context.temporal.timeZone}`, `${context.ambient.defaultTeamId}`, and `${context.ambientStatus}`. If ambient resolution fails, the status is `unavailable`; never invent the missing business facts. Ambient/model-visible context is capped at 16 KiB serialized JSON, depth 8, and 128 entries per container; credential-shaped keys are rejected.
 
 ## Ask for structured missing input
 

package/skills/codex/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/codex/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.

package/skills/codex/references/cli-commands.md

@@ -1,6 +1,6 @@
 # noodle CLI commands
 
-Every `noodle` command, grouped by area. Local authoring commands (`validate`, `test`, `dev`, `tools`, `resources`, `prompts`) need no login or link.
+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
 
@@ -11,7 +11,6 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 - Managed config
 - Governance & observability
 - CLI maintenance
-- Deprecated
 
 ## Authoring & validation
 
@@ -64,7 +63,6 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | `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 list` | Removed — promoted to `deployments list` (prints the recovery pointer and exits 2). |
 | `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). |
 
@@ -87,13 +85,11 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | Command | What it does |
 | :-- | :-- |
 | `noodle audit` | Operator governance audit status and event queries. |
-| `noodle billing` | Super-admin preview of the explicit legacy billing-account migration without writing data (`billing migration preview`). |
 | `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 policy` | Manage policy (status/list/show/effective/simulate/suspend/quota/rate/...). |
-| `noodle platform-auth` | Run aggregate-only super-admin WorkOS inventory, import, reconciliation, rollout, rollback, and finalization operations. |
 
 ## CLI maintenance
 
@@ -103,10 +99,4 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | `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`. |
-
-## Deprecated
-
-| Command | What it does |
-| :-- | :-- |
-| `noodle keys` | Removed: this command no longer exists; hosted access is identity-based. |
+| `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`. |

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

@@ -13,12 +13,12 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 
 | Code | Fix |
 | :-- | :-- |
-| `invalid_context_provider` | Designate at most one normal Core-v2 tool with `contextProvider: true`, and give it an empty object input schema. |
+| `invalid_context_provider` | Designate at most one normal tool with `contextProvider: true`, and give it an empty object input schema. |
 | `yaml_parse_error` | Author in TypeScript; this means the compiled manifest was malformed — re-run from server.ts, do not hand-edit manifest data. |
 | `invalid_shape` | A field has the wrong type or structure; match the shape the compiler reports under `path` against the SDK builder you used. |
 | `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
 | `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
-| `reserved_name` | For Core v1 with `server.context`, rename `noodle_context`; Core v2 does not reserve it and uses an explicit context-provider tool. |
+| `reserved_name` | Rename the reserved identifier and use one explicit zero-input tool with `contextProvider: true` when the model needs application context. |
 | `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
 | `reserved_for_future_version` | The verb at `path` (currently `compute` as a flow step) is reserved for a future core version; express the step with `use` (a connector operation), `map` (a pure mapping), or the shipped `ctx.elicit` input primitive instead. |
 | `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |

package/skills/codex/references/connect-an-api.md

@@ -1,10 +1,13 @@
-# Connect a live API (you were given a key)
+# Outcome
 
-When the user hands you an API key or credentials, don't infer the data from documentation — docs
-drift. Probe the live API, learn the real shape, then encode it as a `connector`. The loop:
+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
@@ -13,9 +16,30 @@ drift. Probe the live API, learn the real shape, then encode it as a `connector`
 - Design intent tools
 - Set the secret for local runs
 - Prove real output
-- Then build the app
+- Verification evidence
+- Recovery paths
+- Stop conditions
 
-## Secure the key first
+## Use when
+
+- The user provides credentials, a reachable API, or an OpenAPI document 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(...)`:
@@ -28,7 +52,7 @@ noodle secrets set SOME_API_KEY --runtime local --from-env SOME_API_KEY   # same
 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
+### 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:
@@ -40,7 +64,7 @@ you will use, and read its field names, nesting, array shapes, pagination, and i
   '${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
+### 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`:
@@ -56,7 +80,7 @@ Encode the API as an HTTP connector, mapping only the fields you actually saw in
 The full connector shape, every `auth.kind`, and compute connectors are in
 `references/authoring-workflow.md`.
 
-## Return a list
+### 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:
 
@@ -87,7 +111,7 @@ pagination: {
 response: { tasks: '${response.items}' },
 ```
 
-## Create, update, delete
+### 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.
@@ -117,14 +141,14 @@ close_task: {
 },
 ```
 
-## Design intent tools
+### Design intent tools
 
-Shape tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
+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
+### 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:
 
@@ -137,17 +161,33 @@ noodle secrets set SOME_API_KEY --runtime local --scope env --org <org> --app <a
 
 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
+### 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, fix the `${response…}` paths against the real payload and re-run.
-Only run a live write if it is safe or the user approved it.
+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.
 
-## Then build the app
+## Stop conditions
 
-With real data flowing, design the experience (`references/experience-design.md`), add widgets where a
-UI genuinely helps (`references/widgets-and-apps.md`), and verify with `noodle check`. Deploy per
-`references/deploy-and-ops.md`, and set the same secret in the hosted environment with `noodle secrets
-set` before the first hosted call.
+- 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.