@noodleseed/agent-kit 0.34.0 → 0.35.0

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

package/skills/claude-code/references/deploy-and-ops.md

@@ -1,89 +1,25 @@
-# Deploy and operations
+# Hosted mutation authorization
 
-## Contents
+> This route changes hosted or external state. Use it only when the current user request explicitly authorizes the exact mutation and target.
 
-- Authenticate
-- Link and target
-- Deploy and inspect
-- Installed Developer plugin handoff
-- Eject path (portable manifest)
-- Connect into a host
-- Access modes
-- Org and members
-- Config and observability
-- Agent-safe CLI recipes
-- Analytics
+## Route boundary
 
-## Authenticate
+- Select this route only for the exact hosted mutation the user requested.
+- Route inspection, diagnosis, preparation, validation, testing, and other read-only work to their read-only references. Those requests do not authorize a mutation.
+- Authentication, target binding, configuration, access changes, deployment, connection writes, and rollback are separate mutations. Authorization for one does not imply another.
 
-`noodle login` to authenticate with Noodle Seed Cloud, `noodle whoami` to confirm, `noodle logout` to clear credentials. Local commands (`dev`/`validate`/`test`) need none of this.
+## Authorization check
 
-## Link and target
+Before any mutation, require the current request to name both the action and its complete target. A mutation-capable target consists of an explicit organization, application, and environment. When the environment is absent, stop and ask for it instead of applying a default, reusing local state, or selecting a target implicitly.
 
-`noodle link --org <slug> --app <slug> [--env <slug>]` binds the directory to a target. Unlinked, `noodle deploy` uses your default org, the project name as the app, and `prod`. `noodle target show|set` inspects or changes the target.
+Do not broaden a request to prepare, inspect, diagnose, or validate into permission to authenticate, bind a target, change configuration or access, deploy, connect, submit, or roll back.
 
-## Deploy and inspect
+## Command and service contract
 
-`noodle deploy` deploys the server. Then `noodle open` (latest URL), `noodle status`, `noodle inspect` (metadata, no secrets), `noodle smoke` (readiness diagnostics), and `noodle rollback <deploymentId>` to revert.
+Use `references/cli-commands.md` as the generated command, flag, and exit-code contract. Consult the live command catalog before acting, and treat the service response as the authority for resulting hosted state. This reference intentionally does not duplicate operational command sequences, defaults, or status semantics.
 
-## Installed Developer plugin handoff
+## Evidence and stop conditions
 
-When this project was bootstrapped by the installed Noodle Developer plugin, preserve its managed launcher invocation for every local CLI command. After `deploy --json`, take the returned deployment ID to the connected remote `noodle-developer.inspect_deployment` tool. Use `noodle-developer.diagnose_app` only when the Cloud evidence needs diagnosis. Those tools inspect the selected organization and environment; they do not edit or replace the application source, which remains the coding agent's responsibility.
-
-## Eject path (portable manifest)
-
-`noodle export manifest [--output <file>]` compiles the entrypoint locally and emits the portable, vendor-neutral manifest JSON — no service, no login, no account. A Noodle app is just `src/server.ts` plus this manifest: the user can read it, diff it, and keep it.
-
-## Connect into a host
-
-Once deployed, register the server as a tool in a host with `noodle connect <host>` (`claude-code`, `codex`, `chatgpt`, `cursor`, `vscode`, `claude`, `inspector`) — it prints the exact config to paste.
-
-- **Claude Code / Claude Desktop** (verified) — add the `mcpServers` block, or one-shot `claude mcp add-json noodle-server '<json>'`:
-
-```json
-{
-  "mcpServers": {
-    "noodle-server": { "type": "https", "url": "https://<app>.mcp.noodleseed.dev" }
-  }
-}
-```
-
-- **Codex / Cursor / VS Code** — the same `mcpServers` block is emitted as a starting point (these hosts' config formats are not officially documented). Wiring a deployed Noodle server into Codex means registering that block in Codex's MCP config.
-- **ChatGPT / Claude.ai** — no config file: open the host's Settings → Connectors → Add custom connector, paste the MCP URL, then authenticate.
-- `noodle connect codex|claude-code --write` writes the project-local agent files (only these two targets).
-
-## Access modes
-
-`noodle access set owner-only|org-members|authenticated|customers` controls who can call the deployed server. Hosted access is identity-based; never add static data-plane keys.
-
-## Org and members
-
-`noodle orgs list|create` and `noodle members list|add|remove --org <slug>` manage organizations and membership.
-
-## Config and observability
-
-Manage runtime config with `noodle secrets` / `noodle variables` (scoped org/app/env). Operators use `noodle logs`, `noodle audit`, and `noodle policy` for logs, governance audit, and policy.
-
-## Agent-safe CLI recipes
-
-Use explicit flags in headless runs so commands never wait for a prompt:
-
-```sh
-noodle link --org acme --app support-assistant --env prod
-noodle secrets set CRM_TOKEN --scope env --org acme --app support-assistant --env prod --from-env CRM_TOKEN
-noodle secrets set CRM_CERT --scope env --org acme --app support-assistant --env prod --from-file ./cert.pem
-printf %s "$CRM_TOKEN" | noodle secrets set CRM_TOKEN --scope env --org acme --app support-assistant --env prod --from-stdin
-noodle variables set CRM_BASE_URL --scope env --org acme --app support-assistant --env prod --value https://crm.example.com
-noodle secrets list --scope env --org acme --app support-assistant --env prod --json
-noodle validate --json
-noodle test --json
-noodle deploy --json
-noodle smoke --json
-noodle agents doctor --json
-```
-
-`secrets resolve` is for local diagnostics only; do not print resolved values into prompts, logs, tests, or docs. Prefer `--from-env`, `--from-file`, or `--from-stdin` over inline `--value` for sensitive values. Variables may use `--value` when the value is non-secret.
-
-## Analytics (verify after deploy, debug errors)
-
-After a deploy gets traffic, verify with `noodle metrics --agent-output` — it returns a `health` verdict (`ok`/`attention`), a one-line summary, and `attention[]` items each carrying the exact next command. When a tool errors, drill in with `noodle events --tool <name> --json` (filters: `--status tool_error|mcp_error`, `--client <name>`); `noodle events --session <id> --json` replays one session chronologically. `--json` on both returns the full payload; human runs get the branded report. Two-tier errors: `tool_error` is recoverable (handed back to the model), `mcp_error` needs attention (protocol/timeout/internal). Wire edge-triggered webhooks on error share, error count, calls, or p95 latency with `noodle alerts add|list|remove|test`.
+- Stop before execution when the action or complete target is missing.
+- After an authorized mutation, report only the state evidenced by the command and service response.
+- Do not claim host behavior, production health, or successful external registration without direct evidence at that layer.

package/skills/claude-code/references/experience-design.md

@@ -126,7 +126,7 @@ The design phase produces up to three artifacts — worked gold-standard version
   architecture, demo scope, success metrics, and future enhancements — opening on the funnel-boundary
   line every scope debate resolves against.
 - **Wireframe** — the single-file HTML alignment artifact (anatomy above) with the embedded compliance
-  audit; see `references/chatgpt-compliance.md`.
+  audit; see `references/app-directory-compliance.md`.
 - **API contract** — when the partner's backend must be built or wrapped. Escalate: (1) the MCP
   tool→call-sequence map (always); (2) "Recommended API Shapes" — concrete request/response JSON per
   tool, including the hardest nested case; (3) a full OpenAPI spec for transactional apps. Contract

package/skills/claude-code/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, use its deployment inspection or diagnosis tool only for the selected org/app/env. Treat it as 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/references/publishing.md

@@ -1,31 +1,29 @@
 # Publish to app directories
 
-Directory requirements evolve — treat this as the workflow map and verify against the host’s current submission docs before submitting.
+> Preparation is read-only unless the current user request explicitly authorizes the exact deploy, access change, host write, or submission target. A request to prepare must report missing readiness work and stop before mutation.
+
+Directory requirements evolve. Identify the requested directory first and verify its current official requirements before preparing directory-specific evidence.
 
 ## Contents
 
-- Readiness gate
-- ChatGPT apps directory
-- Claude connectors directory
+- Shared readiness gate
+- Directory-specific evidence
+- Submission boundary
 
-## Readiness gate
+## Shared readiness gate
 
 Before any submission:
 
-1. `noodle check --target chatgpt` must be clean — every widget needs `domain` (one https origin per app) and an exact `csp` (hosts require the CSP to list precisely the domains you fetch from).
-2. Audit tool responses in developer mode: run realistic prompts and strip anything not strictly needed — PII, internal identifiers (session/trace/request IDs, internal account IDs), and any secrets.
-3. The server must be deployed and publicly reachable: `noodle deploy`, confirm with `noodle open --print` and `noodle smoke`. Reviewers connect to the real endpoint — never submit a placeholder or loopback URL, and the access mode must not be `owner-only` (`noodle access set`).
-4. Polish the listing surface: tool descriptions, widget titles, and the `server` branding tokens are what reviewers and users see.
+Use `references/app-directory-compliance.md` as this route’s canonical shared compliance checklist.
+
+Prepare evidence for a reachable production MCP endpoint, accurate capability descriptions and schemas, useful fallback behavior, realistic positive and negative tests, data minimization, privacy disclosures, support ownership, and any interactive surface the directory will review.
 
-## ChatGPT apps directory
+## Directory-specific evidence
 
-Submit from the OpenAI developer dashboard (platform.openai.com → Apps):
+Read the selected directory’s current official submission documentation at review time. Record each additional requirement separately from the shared checklist, including listing fields, identity verification, test credentials, screenshots, policy declarations, review limits, and appeal or resubmission steps. Never project one directory’s requirements onto another.
 
-- Complete organization identity verification first (individual or business) — it is enforced at review time.
-- The submission form asks for the app name, logo, description, company and privacy policy URLs, MCP server URL and tool information, screenshots, test prompts with expected responses, and localization details.
-- One version may be published and one in review at a time; to revise a pending submission, cancel the review and resubmit rather than creating a new app.
-- Review combines automated checks and manual evaluation; rejections come with feedback — fix and resubmit, or reply to appeal. An approved app is also distributed as a Codex plugin.
+When a requirement cannot be verified from the selected directory’s current documentation or direct review evidence, mark it unknown instead of borrowing a rule from another host.
 
-## Claude connectors directory
+## Submission boundary
 
-Anthropic runs a connectors directory for Claude; submission goes through Anthropic’s published process (see the Anthropic connectors directory FAQ on support.claude.com). The same readiness gate applies: deployed public endpoint, clean `noodle check`, and graceful degradation where Apps rendering is unavailable.
+Preparation is read-only. Deployment, access changes, directory registration, and final submission each require explicit authorization for the exact target. Report remaining evidence gaps and stop when that authority or required directory access is absent.

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

@@ -0,0 +1,65 @@
+# 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 and exercises registration.
+4. **Real API** — a representative safe `noodle tools call` proves connector credentials, transport, observed mapping, and populated data.
+5. **App compliance** — `noodle check --json` and local devtools prove the App contract and intended states.
+6. **Host** — the requested host connects, invokes the expected capability, and renders useful fallback/UI behavior.
+7. **Deploy** — the requested hosted revision and configuration exist and report healthy at the deployment layer.
+8. **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.
+- 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/codex/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:25832eb0ac3cd277 -->
+<!-- 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` — 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/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.