@noodleseed/agent-kit 0.65.0 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ 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.65.0 hash:7732a64aac011333 -->
+<!-- noodle-skill version:0.66.0 hash:13ddce01769caae4 -->
 
 # Noodle Seed
 
@@ -19,13 +19,14 @@ If the request is unrelated to the Noodle MCP surface, stop here: follow the pro
 
 Choose exactly one primary route from the user outcome below, then load the selected sibling skill and hand off the request. Read that primary reference in full; read supporting references only when the sibling or observed evidence requires them. Do not reread the corpus or restart discovery after the handoff.
 
-Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take precedence over generic server building; hosted inspection is debugging read-only; hosted mutation requires the explicitly requested deployment route.
+Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an explicit request to create, revise, regenerate, or recover an app product skill takes `creating-product-agent-guides`; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take precedence over generic server building; hosted inspection is debugging read-only; 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.
 
 | User outcome | Load sibling skill | Canonical playbook | Done when |
 | :--- | :--- | :--- | :--- |
 | Turn a vague MCP product idea into a bounded design before implementation | `designing-mcp-products` | `references/experience-design.md` (`references/authoring-workflow.md`) | The product contract identifies the user benefit, model boundary, evidence, and next implementation skill. |
+| Create, revise, regenerate, or recover the product skill for this MCP server | `creating-product-agent-guides` | `references/product-agent-guides.md` (None) | The grounded TypeScript guide and generated-file plan are proven, with each approved write applied explicitly or left pending. |
 | Plan how to wrap an existing application that has no stable usable public API | `wrapping-existing-applications` | `references/wrap-existing-app.md` (`references/authoring-workflow.md`, `references/tool-design.md`) | A sanitized identity-first capability map and repository-scoped implementation plan are presented for approval before mutation. |
 | Create or extend a headless MCP server whose external API contract is already modeled | `authoring-mcp-servers` | `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 only when all four API-evidence inputs exist: API base URL, authentication scheme, representative safe read, and observed response | `connecting-apis-to-mcp` | `references/connect-an-api.md` (`references/authoring-workflow.md`) | A representative live read returns populated, intentionally mapped fields without exposing credentials. |
@@ -56,7 +57,7 @@ Inside the installed plugin, perform mapped steps with `noodle-readiness` tools
 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/product-agent-guides.md` — decide whether a product needs one host-neutral guide, then author it when selected.
+- `references/product-agent-guides.md` — decide, interview, propose, prove, preview, and explicitly install one host-neutral product guide.
 - `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.

package/skills/claude-code/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:11523cb33b9473c0 -->
+<!-- noodle-skill version:0.66.0 hash:11523cb33b9473c0 -->
 
 # authoring-mcp-servers
 

package/skills/claude-code/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:9fd67d4d24328e15 -->
+<!-- noodle-skill version:0.66.0 hash:9fd67d4d24328e15 -->
 
 # building-mcp-apps
 

package/skills/claude-code/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.66.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

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

@@ -0,0 +1,46 @@
+---
+name: creating-product-agent-guides
+description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
+---
+
+<!-- noodle-skill version:0.66.0 hash:0fa48a82fe836cf0 -->
+
+# creating-product-agent-guides
+
+Create or revise one grounded TypeScript product guide, prove it locally, and preview every generated-file change before explicit installation.
+
+## Use when
+
+- Teach agents how to use this MCP product across multiple capabilities.
+- Create, revise, regenerate, or recover an app product skill.
+
+## Do not use when
+
+- Do not use merely to add or change an MCP capability; use the owning server or App build skill.
+- Do not invent product workflows, capability names, or weaker safety boundaries from source shape alone.
+
+## Required inputs
+
+- Configured TypeScript entrypoint and its declared MCP capabilities.
+- Builder-confirmed product triggers, workflow judgment, and boundaries that source cannot prove.
+- Separate approval for source editing and generated app-skill installation or replacement.
+
+## Workflow
+
+Read and follow the canonical playbook `references/product-agent-guides.md` at `../noodle-seed/references/product-agent-guides.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+
+## Verification evidence
+
+The approved TypeScript guide references only declared capabilities, validation and local smoke pass, and the explicit package plan is either approved and applied or left as a preview.
+
+## Recovery paths
+
+Repair structured guide errors by exact path; preserve modified or unowned local files and use only the previewed app-skill recovery action the builder approves.
+
+## Stop conditions
+
+Stop before editing source or materializing generated app-skill files at each separate approval boundary.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/claude-code/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.66.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/claude-code/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.66.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/claude-code/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:78a6f181b61f92f1 -->
+<!-- noodle-skill version:0.66.0 hash:78a6f181b61f92f1 -->
 
 # designing-mcp-products
 

package/skills/claude-code/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.66.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/claude-code/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.66.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/claude-code/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.66.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

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

@@ -16,6 +16,16 @@ A product with a single self-explanatory capability may omit the guide when its
 
 Make the judgment from the user’s stated outcome and grounded product evidence. If a guide is warranted but a decision-changing workflow or boundary is unknown, ask only for that missing product input; never fabricate it. The user should not need to know this feature name to receive the benefit.
 
+## Creation workflow
+
+1. **Inspect grounded capability evidence.** Read the configured TypeScript entrypoint (`server.ts` or `src/server.ts`) and identify its exact declared tools, resources, prompts, descriptions, visibility, annotations, authorization, and widget relationships. Treat schemas and compiled annotations as facts. Never invent or guess a tool, resource, prompt, capability kind, workflow, or weaker write boundary.
+2. **Decide guided or unguided.** Apply the criteria above and state the decision with its evidence. If the existing capabilities are self-explanatory and no product judgment is missing, recommend an intentionally unguided server and stop this workflow.
+3. **Interview only for product judgment.** Ask the builder for the decision-changing triggers, workflow ordering, grounding or clarification rules, boundaries, and representative prompts that source cannot prove. Do not ask them to restate capability names or schemas already present in TypeScript.
+4. **Propose TypeScript.** Present the complete proposed `agentGuide` block, map every step to one exact declared capability and kind, and call out how write, destructive, open-world, confirmation, authorization, and widget boundaries remain unchanged. Request explicit approval before editing the configured TypeScript entrypoint.
+5. **Apply and prove after approval.** Add or revise only the approved TypeScript guide. Run `noodle validate --json`, repair each structured guide error at its exact path without free-form invention, then run `noodle test --json`.
+6. **Preview the App Package plan.** Run `noodle agents setup --json` and report its exact target, file, ownership-migration, removal, and replacement actions. A preview never writes files. For an existing installed app skill, pass `--regenerate-app-skill` to state the intended operation explicitly; add `--replace-modified-app-skill` only when the builder is considering replacement of previously Noodle-owned bytes.
+7. **Ask separately before installation.** Request explicit approval before writing or replacing the app product skill. On approval, run `noodle agents setup --write` for a first installation, or `noodle agents setup --write --regenerate-app-skill` for a changed, migrated, renamed, or removed installation. Add `--replace-modified-app-skill` only when the preview identified modified previously owned bytes and the builder approved losing those exact local modifications.
+
 ## Authoring shape
 
 The guide contains `description`, `useWhen`, named `workflows`, optional `boundaries`, and optional example prompt-to-workflow mappings. Each workflow step references a declared `tool`, `resource`, or `prompt` by symbolic `{ kind, name }`; do not duplicate schemas, connector bindings, URLs, credentials, or raw runtime data.
@@ -26,8 +36,10 @@ Use `server.instructions` for a concise live MCP-session primer. Noodle-owned wo
 
 ## Local lifecycle
 
-`noodle agents setup` previews the local product-skill files compiled from `server.ts`; add `--write` to install them under `.agents/skills/<app-skill>/` and `.claude/skills/<app-skill>/`. No account or hosted deployment is required. The app files have an ownership record separate from the Noodle workflow skills.
+`noodle agents setup` previews the local product-skill files compiled from `server.ts`; add `--write` for the first installation under `.agents/skills/<app-skill>/` and `.claude/skills/<app-skill>/`. No account or hosted deployment is required. The app files have an ownership record separate from the Noodle workflow skills.
+
+A normal `noodle agents setup --write` refreshes Noodle-owned workflow skills but leaves an already installed app product skill unchanged. Regeneration, ownership-schema migration, rename, and removal require `--regenerate-app-skill` and are previewed even when `--write` is present without that flag. `--force` applies only to Noodle-owned project context and never overwrites a modified app-skill file. `--replace-modified-app-skill` is the narrower, separately approved recovery for previously owned app-skill bytes; it never claims unowned collisions or bypasses malformed state.
 
-`noodle agents setup --write` is idempotent and never overwrites a modified app-skill file. `--force` applies only to Noodle-owned project context, not app product skills. Run `noodle agents doctor --json`: `agent_skill_modified` means preserve and review local bytes; `agent_skill_stale` means source, surface, renderer, or installed files changed, so preview before writing; `agent_skill_invalid_state` means the ownership record is malformed or unsafe, so preserve the files and review the record before retrying.
+Run `noodle agents doctor --json`: `agent_skill_modified` means preserve and review local bytes; `agent_skill_stale` means source, surface, renderer, installed files, or ownership schema changed, so preview explicit regeneration; `agent_skill_invalid_state` means the ownership record is malformed or unsafe, so preserve the files and review the record before retrying.
 
 Recover `agent_guide_*` errors by correcting the guide shape, workflow IDs, and capability kind/name. Remove any credential-shaped value: managed config is referenced by name only.

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.66.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.66.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/claude-code/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ name: wrapping-existing-applications
 description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.66.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications
 

package/skills/codex/SKILL.md

@@ -3,7 +3,7 @@ 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.65.0 hash:7732a64aac011333 -->
+<!-- noodle-skill version:0.66.0 hash:13ddce01769caae4 -->
 
 # Noodle Seed
 
@@ -19,13 +19,14 @@ If the request is unrelated to the Noodle MCP surface, stop here: follow the pro
 
 Choose exactly one primary route from the user outcome below, then load the selected sibling skill and hand off the request. Read that primary reference in full; read supporting references only when the sibling or observed evidence requires them. Do not reread the corpus or restart discovery after the handoff.
 
-Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take precedence over generic server building; hosted inspection is debugging read-only; hosted mutation requires the explicitly requested deployment route.
+Apply this precedence when wording overlaps: concrete failure evidence takes the debugging route; an explicit request to create, revise, regenerate, or recover an app product skill takes `creating-product-agent-guides`; an MCP App/UI outcome takes the App route; an existing application with no stable, usable API or specification takes `wrapping-existing-applications`; only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use `connecting-apis-to-mcp`; missing, stale, inaccessible, undocumented-only, or otherwise unusable evidence remains in `wrapping-existing-applications`; both integration routes take precedence over generic server building; hosted inspection is debugging read-only; 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.
 
 | User outcome | Load sibling skill | Canonical playbook | Done when |
 | :--- | :--- | :--- | :--- |
 | Turn a vague MCP product idea into a bounded design before implementation | `designing-mcp-products` | `references/experience-design.md` (`references/authoring-workflow.md`) | The product contract identifies the user benefit, model boundary, evidence, and next implementation skill. |
+| Create, revise, regenerate, or recover the product skill for this MCP server | `creating-product-agent-guides` | `references/product-agent-guides.md` (None) | The grounded TypeScript guide and generated-file plan are proven, with each approved write applied explicitly or left pending. |
 | Plan how to wrap an existing application that has no stable usable public API | `wrapping-existing-applications` | `references/wrap-existing-app.md` (`references/authoring-workflow.md`, `references/tool-design.md`) | A sanitized identity-first capability map and repository-scoped implementation plan are presented for approval before mutation. |
 | Create or extend a headless MCP server whose external API contract is already modeled | `authoring-mcp-servers` | `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 only when all four API-evidence inputs exist: API base URL, authentication scheme, representative safe read, and observed response | `connecting-apis-to-mcp` | `references/connect-an-api.md` (`references/authoring-workflow.md`) | A representative live read returns populated, intentionally mapped fields without exposing credentials. |
@@ -56,7 +57,7 @@ Inside the installed plugin, perform mapped steps with `noodle-readiness` tools
 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/product-agent-guides.md` — decide whether a product needs one host-neutral guide, then author it when selected.
+- `references/product-agent-guides.md` — decide, interview, propose, prove, preview, and explicitly install one host-neutral product guide.
 - `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.

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:11523cb33b9473c0 -->
+<!-- noodle-skill version:0.66.0 hash:11523cb33b9473c0 -->
 
 # authoring-mcp-servers
 

package/skills/codex/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:9fd67d4d24328e15 -->
+<!-- noodle-skill version:0.66.0 hash:9fd67d4d24328e15 -->
 
 # building-mcp-apps
 

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when all four API-evidence inputs exist—and only then: API base URL, authentication scheme, representative safe read, and observed response."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:21bbd3ec441ffd30 -->
+<!-- noodle-skill version:0.66.0 hash:21bbd3ec441ffd30 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/creating-product-agent-guides/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: creating-product-agent-guides
+description: "Use when a Noodle Seed MCP server needs a new or revised product agent guide, App Package skill, or explicit product-skill regeneration."
+---
+
+<!-- noodle-skill version:0.66.0 hash:0fa48a82fe836cf0 -->
+
+# creating-product-agent-guides
+
+Create or revise one grounded TypeScript product guide, prove it locally, and preview every generated-file change before explicit installation.
+
+## Use when
+
+- Teach agents how to use this MCP product across multiple capabilities.
+- Create, revise, regenerate, or recover an app product skill.
+
+## Do not use when
+
+- Do not use merely to add or change an MCP capability; use the owning server or App build skill.
+- Do not invent product workflows, capability names, or weaker safety boundaries from source shape alone.
+
+## Required inputs
+
+- Configured TypeScript entrypoint and its declared MCP capabilities.
+- Builder-confirmed product triggers, workflow judgment, and boundaries that source cannot prove.
+- Separate approval for source editing and generated app-skill installation or replacement.
+
+## Workflow
+
+Read and follow the canonical playbook `references/product-agent-guides.md` at `../noodle-seed/references/product-agent-guides.md`. It owns the workflow; do not recreate it here or load the command catalog speculatively.
+
+## Verification evidence
+
+The approved TypeScript guide references only declared capabilities, validation and local smoke pass, and the explicit package plan is either approved and applied or left as a preview.
+
+## Recovery paths
+
+Repair structured guide errors by exact path; preserve modified or unowned local files and use only the previewed app-skill recovery action the builder approves.
+
+## Stop conditions
+
+Stop before editing source or materializing generated app-skill files at each separate approval boundary.
+
+## Handoff contract
+
+Pass the selected outcome, explicit target, changed files, commands run, passing evidence, first unproven evidence layer, sanitized failure, remaining authority, and exact next action. The receiving skill continues from that layer; do not restart discovery or discard prior proof.

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.66.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.66.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:78a6f181b61f92f1 -->
+<!-- noodle-skill version:0.66.0 hash:78a6f181b61f92f1 -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.66.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.66.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.66.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/product-agent-guides.md

@@ -16,6 +16,16 @@ A product with a single self-explanatory capability may omit the guide when its
 
 Make the judgment from the user’s stated outcome and grounded product evidence. If a guide is warranted but a decision-changing workflow or boundary is unknown, ask only for that missing product input; never fabricate it. The user should not need to know this feature name to receive the benefit.
 
+## Creation workflow
+
+1. **Inspect grounded capability evidence.** Read the configured TypeScript entrypoint (`server.ts` or `src/server.ts`) and identify its exact declared tools, resources, prompts, descriptions, visibility, annotations, authorization, and widget relationships. Treat schemas and compiled annotations as facts. Never invent or guess a tool, resource, prompt, capability kind, workflow, or weaker write boundary.
+2. **Decide guided or unguided.** Apply the criteria above and state the decision with its evidence. If the existing capabilities are self-explanatory and no product judgment is missing, recommend an intentionally unguided server and stop this workflow.
+3. **Interview only for product judgment.** Ask the builder for the decision-changing triggers, workflow ordering, grounding or clarification rules, boundaries, and representative prompts that source cannot prove. Do not ask them to restate capability names or schemas already present in TypeScript.
+4. **Propose TypeScript.** Present the complete proposed `agentGuide` block, map every step to one exact declared capability and kind, and call out how write, destructive, open-world, confirmation, authorization, and widget boundaries remain unchanged. Request explicit approval before editing the configured TypeScript entrypoint.
+5. **Apply and prove after approval.** Add or revise only the approved TypeScript guide. Run `noodle validate --json`, repair each structured guide error at its exact path without free-form invention, then run `noodle test --json`.
+6. **Preview the App Package plan.** Run `noodle agents setup --json` and report its exact target, file, ownership-migration, removal, and replacement actions. A preview never writes files. For an existing installed app skill, pass `--regenerate-app-skill` to state the intended operation explicitly; add `--replace-modified-app-skill` only when the builder is considering replacement of previously Noodle-owned bytes.
+7. **Ask separately before installation.** Request explicit approval before writing or replacing the app product skill. On approval, run `noodle agents setup --write` for a first installation, or `noodle agents setup --write --regenerate-app-skill` for a changed, migrated, renamed, or removed installation. Add `--replace-modified-app-skill` only when the preview identified modified previously owned bytes and the builder approved losing those exact local modifications.
+
 ## Authoring shape
 
 The guide contains `description`, `useWhen`, named `workflows`, optional `boundaries`, and optional example prompt-to-workflow mappings. Each workflow step references a declared `tool`, `resource`, or `prompt` by symbolic `{ kind, name }`; do not duplicate schemas, connector bindings, URLs, credentials, or raw runtime data.
@@ -26,8 +36,10 @@ Use `server.instructions` for a concise live MCP-session primer. Noodle-owned wo
 
 ## Local lifecycle
 
-`noodle agents setup` previews the local product-skill files compiled from `server.ts`; add `--write` to install them under `.agents/skills/<app-skill>/` and `.claude/skills/<app-skill>/`. No account or hosted deployment is required. The app files have an ownership record separate from the Noodle workflow skills.
+`noodle agents setup` previews the local product-skill files compiled from `server.ts`; add `--write` for the first installation under `.agents/skills/<app-skill>/` and `.claude/skills/<app-skill>/`. No account or hosted deployment is required. The app files have an ownership record separate from the Noodle workflow skills.
+
+A normal `noodle agents setup --write` refreshes Noodle-owned workflow skills but leaves an already installed app product skill unchanged. Regeneration, ownership-schema migration, rename, and removal require `--regenerate-app-skill` and are previewed even when `--write` is present without that flag. `--force` applies only to Noodle-owned project context and never overwrites a modified app-skill file. `--replace-modified-app-skill` is the narrower, separately approved recovery for previously owned app-skill bytes; it never claims unowned collisions or bypasses malformed state.
 
-`noodle agents setup --write` is idempotent and never overwrites a modified app-skill file. `--force` applies only to Noodle-owned project context, not app product skills. Run `noodle agents doctor --json`: `agent_skill_modified` means preserve and review local bytes; `agent_skill_stale` means source, surface, renderer, or installed files changed, so preview before writing; `agent_skill_invalid_state` means the ownership record is malformed or unsafe, so preserve the files and review the record before retrying.
+Run `noodle agents doctor --json`: `agent_skill_modified` means preserve and review local bytes; `agent_skill_stale` means source, surface, renderer, installed files, or ownership schema changed, so preview explicit regeneration; `agent_skill_invalid_state` means the ownership record is malformed or unsafe, so preserve the files and review the record before retrying.
 
 Recover `agent_guide_*` errors by correcting the guide shape, workflow IDs, and capability kind/name. Remove any credential-shaped value: managed config is referenced by name only.

package/skills/codex/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.66.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/codex/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.66.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/wrapping-existing-applications/SKILL.md

@@ -3,7 +3,7 @@ name: wrapping-existing-applications
 description: "Use when an existing application has no stable usable API and needs a read-only, identity-first Noodle Seed integration plan before implementation."
 ---
 
-<!-- noodle-skill version:0.65.0 hash:eccc3c158dcafba8 -->
+<!-- noodle-skill version:0.66.0 hash:eccc3c158dcafba8 -->
 
 # wrapping-existing-applications