@noodleseed/agent-kit 0.33.0 → 0.35.0

package/skills/claude-code/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/claude-code/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/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,94 +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.
-
-## Billing migration preview
-
-`noodle billing migration preview [--file <mapping.json>]` is a super-admin, read-only inventory and validation command for legacy organizations. It never creates billing accounts, links organizations, or changes entitlements, and there is no apply command. Keep real mapping files outside the repository. The versioned file must classify production apps for every organization: `linkState: "unlinked"` selects a current owner subject under the fixed hosted issuer `https://accounts.google.com`, while `linkState: "linked"` asserts the exact current billing-account ID and link version. Inventory apps with `noodle apps list --archived --json` so archive state is visible. A blocked preview exits 1 even though the JSON response is a successful preview envelope; inspect `data.preview.blockers` and resolve every blocker before a future cutover workflow exists.
-
-## 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 billing migration preview --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/embedded-assistant.md

@@ -180,7 +180,7 @@ context: {
 },
 ```
 
-The callback records declarative fulfilment at author time; the shared runtime executes only read-only connector operations, validates the declared output, and freezes one snapshot for the whole invocation and any accepted interaction. Tools/resources/prompts read `context.temporal`, `context.ambient`, and `context.ambientStatus`. The embedded assistant receives the same snapshot in trusted platform context. For model-visible application context in every host, designate one normal zero-input tool with `contextProvider: true`; the embedded host preloads it per turn and external hosts call it normally. Core-v1 `server.context` retains the legacy reserved `noodle_context` adapter, while canonical Core-v2 TypeScript authoring does not create or reserve it. Keep ambient facts compact: the platform caps serialized JSON at 16 KiB, depth 8, and 128 entries per container, and rejects credential-shaped keys.
+The callback records declarative fulfilment at author time; the shared runtime executes only read-only connector operations, validates the declared output, and freezes one snapshot for the whole invocation and any accepted interaction. Tools/resources/prompts read `context.temporal`, `context.ambient`, and `context.ambientStatus`. The embedded assistant receives the same snapshot in trusted platform context. For model-visible application context in every host, designate one normal zero-input tool with `contextProvider: true`; the embedded host preloads it per turn and external hosts call it normally. Keep ambient facts compact: the platform caps serialized JSON at 16 KiB, depth 8, and 128 entries per container, and rejects credential-shaped keys.
 
 ## Structured missing input
 
@@ -304,7 +304,7 @@ if (pendingId) {
 - Signed-out session exchange returns `401`.
 - The browser network/DOM/storage contains no client secret or model key.
 - The local and production origins match `allowedOrigins` character-for-character.
-- At the manifest/runtime boundary and in TypeScript action helpers, only `confirm: true` enables confirmation; omitted or `false` preserves Core-v1 direct execution. Action hints alone never enforce approval; `annotations.action({ confirm: false })` is equivalent to omission.
+- At the manifest/runtime boundary and in TypeScript action helpers, only `confirm: true` enables confirmation; omitted or `false` preserves direct execution. Action hints alone never enforce approval; `annotations.action({ confirm: false })` is equivalent to omission.
 - An expired turn re-exchanges once; interaction decisions never auto-retry. An explicit same-decision repeat returns the stored outcome without executing again.
 - Accept, decline, and cancel are single-use. Only accept executes; the server ignores replacement tool arguments.
 - Wrong-origin and malformed-origin requests fail closed.
@@ -328,6 +328,6 @@ if (pendingId) {
 | Relative dates use the wrong day or time zone | No verified user preference and the browser hint is missing/stale | Pass saved `preferences` from the backend; provide a fresh per-turn `clientContext` in a headless renderer |
 | The model invents a team/holiday after context lookup fails | The ambient provider returned invalid data or its read-only connector failed (`ambientStatus: unavailable`) | Fix the provider/connector; treat unavailable ambient facts as missing, never prompt instructions |
 | Decline/cancel reports `unsupported_service` | The session came from a legacy service with no `endpoints.interactions` | Upgrade the service; legacy `toolConfirmations` supports accept only |
-| Behavior does not change after `noodle deploy` | Outdated platform: before the 2026-07 fix, clients were pinned to their creation-time deployment | Update the platform; sessions now follow the tenant's active deployment |
+| Behavior does not change after `noodle deploy` | The client is not following the tenant's active deployment | Restart the client session and confirm the selected tenant and deployment |
 | A delegated connector returns `credential_unavailable` / `caller_identity_not_customer` | The calling surface has no verified customer identity (or an old session minted before the platform carried the resource audience) | Verify `customerAuth` is configured, the backend passes the verified `user`, and run `noodle auth doctor --live` |
 | Deploy fails with `unsupported_delegated_provider` | `delegatedOAuth.provider` only supports the managed `firebase`/`microsoft` bridges | Use `auth.kind: "delegatedTokenExchange"` for your own token endpoint (see authoring-workflow.md) |

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/feedback.md

@@ -1,19 +1,20 @@
 # Send product feedback
 
-When you — the coding agent — discover a way Noodle Seed could be better, tell the team with one command. Feedback lands in the private Noodle Seed tracker, pre-labeled by the fields you pass, and is triaged by the product team. Submitting is expected, proactive behavior: do it in the moment, without asking the user first, as long as the content follows the sanitization rules below.
+When you — the coding agent — discover a way Noodle Seed could be better, prepare one sanitized feedback proposal. Feedback crosses the customer project boundary and lands in Noodle Seed’s private tracker, so the user must make an informed choice. Show the user the exact command and ask for explicit user approval. Do not run or submit it until approval is given.
 
 ## Contents
 
-- When to send feedback (proactive triggers)
+- When to propose feedback
+- Approval workflow
 - The command
 - Choose the structured fields
 - Sanitization rules (hard requirements)
 - Minimal repro guidance
 - After you submit
 
-## When to send feedback (proactive triggers)
+## When to propose feedback
 
-Send one `noodle feedback` per distinct finding whenever you:
+Draft one `noodle feedback` proposal per distinct finding when you:
 
 - hit a CLI or SDK error that cost you retries, or whose message/`fix`/`next` guidance misled you;
 - discover a missing capability you had to work around (in the CLI, SDK, widgets, connectors, deploy lane, console, or docs);
@@ -21,7 +22,14 @@ Send one `noodle feedback` per distinct finding whenever you:
 - notice confusing command output, a broken `--json` envelope, or a wrong exit code;
 - have a concrete idea that would make authoring or operating apps faster.
 
-Do not batch several findings into one submission, and do not re-submit the same finding in the same session. Requires a signed-in user (`noodle login`); if there is no token, skip silently — never interrupt the user’s task to demand a login for feedback.
+Do not batch several findings into one proposal, and do not re-propose the same finding in the same session.
+
+## Approval workflow
+
+1. Draft and sanitize the title, message, labels, and exact shell command.
+2. Show the user the exact command and explain that it sends the shown content plus CLI version, OS/platform, and Node version to Noodle Seed’s private tracker.
+3. Ask for explicit user approval. Do not run, submit, or send anything until the user clearly approves that exact proposal.
+4. After approval, run it once. If authentication is missing, report that feedback was not sent and offer the normal `noodle login` path; never sign in or retry without direction.
 
 ## The command
 
@@ -31,7 +39,7 @@ noodle feedback "resources list --json omits the truncated flag the docs promise
   --type fix --severity P2 --area cli --json
 ```
 
-The message is required (1–4000 chars). Pass `--json` and parse the envelope: success is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — drop the submission, never retry-loop. The CLI attaches only light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected.
+This is an example only; build the exact command for the finding and show it before execution. The message is required (1–4000 chars). Pass `--json` and parse the envelope: success is `{ok:true,data:{reference,labels}}`; a `429` means the per-user hourly budget (5) is spent — report that it was not sent and never retry-loop. The CLI attaches only the disclosed light diagnostics automatically: CLI version, OS/platform, Node version. Nothing else is collected.
 
 ## Choose the structured fields
 
@@ -64,4 +72,4 @@ Repro: applies to every connector whose response mapping references a nested arr
 
 ## After you submit
 
-The returned `reference` (e.g. `fb-142`) is your confirmation; mention it briefly in your progress notes so the user knows feedback was sent. Feedback goes to a private tracker — there is no public issue link, and no follow-up action is needed. Continue the user’s task immediately; feedback must never block or slow their work.
+Only after explicit user approval and a successful command, the returned `reference` (e.g. `fb-142`) is confirmation; mention it briefly so the user knows what was sent. Feedback goes to a private tracker — there is no public issue link, and no follow-up action is needed. Continue the user’s task immediately; feedback must never block or slow their work.

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/claude-code/references/widgets-and-apps.md

@@ -18,7 +18,7 @@ Use `tool(name, { description, input, output, fulfil, view })` for a model-visib
 
 Generated widgets, official examples, and agent-authored MCP Apps must start with `@noodleseed/one/react` primitives and semantic tokens. Custom React/CSS or third-party components remain valid when the kit lacks the required behavior or the developer explicitly requests them.
 
-`noodle init my-app` defaults to the Core-v2 SaaS profile: federated OIDC placeholders, one explicit context-provider tool, MCP App UI, resource, prompt, state contract, branding, handoff, and embedded assistant. Begin by replacing the IdP/audience/domain placeholders. Use `--template widget`, `hello`, or `http-api` only when that narrower profile is intentional.
+`noodle init my-app` defaults to the SaaS profile: federated OIDC placeholders, one explicit context-provider tool, MCP App UI, resource, prompt, state contract, branding, handoff, and embedded assistant. Begin by replacing the IdP/audience/domain placeholders. Use `--template widget`, `hello`, or `http-api` only when that narrower profile is intentional.
 
 The default composition rule is: build the smallest useful conversational surface. Inline has one purpose, one primary action, and at most two visible actions. Use progressive disclosure or a later conversational turn for secondary detail; request fullscreen only when the user asks or the task genuinely needs it. Never use nested scrolling. At 280px and wider, the widget must remain one-column, readable, touch-safe, and free of horizontal overflow. Remove secondary chrome before shrinking essential content.