@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/chatgpt-apps/LICENSE.txt

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!) The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/skills/chatgpt-apps/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: chatgpt-apps
+description: Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.
+---
+
+# ChatGPT Apps
+
+## Overview
+
+Scaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.
+
+Use this skill to produce:
+
+- A primary app-archetype classification and repo-shape decision
+- A tool plan (names, schemas, annotations, outputs)
+- An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)
+- An MCP server scaffold (resource registration, tool handlers, metadata)
+- A widget scaffold (MCP Apps bridge first, `window.openai` compatibility/extensions second)
+- A reusable Node + `@modelcontextprotocol/ext-apps` starter scaffold for low-dependency fallbacks
+- A validation report against the minimum working repo contract
+- Local dev and connector setup steps
+- A short stakeholder summary of what the app does (when requested)
+
+## Mandatory Docs-First Workflow
+
+Use `$openai-docs` first whenever building or changing a ChatGPT Apps SDK app.
+
+1. Invoke `$openai-docs` (preferred) or call the OpenAI docs MCP server directly.
+2. Fetch current Apps SDK docs before writing code, especially (baseline pages):
+   - `apps-sdk/build/mcp-server`
+   - `apps-sdk/build/chatgpt-ui`
+   - `apps-sdk/build/examples`
+   - `apps-sdk/plan/tools`
+   - `apps-sdk/reference`
+3. Fetch `apps-sdk/quickstart` when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.
+4. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:
+   - `apps-sdk/deploy`
+   - `apps-sdk/deploy/submission`
+   - `apps-sdk/app-submission-guidelines`
+5. Cite the docs URLs you used when explaining design choices or generated scaffolds.
+6. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
+7. If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.
+
+If `$openai-docs` is unavailable, use:
+
+- `mcp__openaiDeveloperDocs__search_openai_docs`
+- `mcp__openaiDeveloperDocs__fetch_openai_doc`
+
+Read `references/apps-sdk-docs-workflow.md` for suggested doc queries and a compact checklist.
+Read `references/app-archetypes.md` to classify the request into a small number of supported app shapes before choosing examples or scaffolds.
+Read `references/repo-contract-and-validation.md` when generating or reviewing a repo so the output stays inside a stable “working app” contract.
+Read `references/search-fetch-standard.md` when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research.
+Read `references/upstream-example-workflow.md` when starting a greenfield app or when deciding whether to adapt an upstream example or use the local fallback scaffold.
+Read `references/window-openai-patterns.md` when the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific `app.*` helpers.
+
+## Prompt Guidance
+
+Use prompts that explicitly pair this skill with `$openai-docs` so the resulting scaffold is grounded in current docs.
+
+Preferred prompt patterns:
+
+- `Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.`
+- `Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.`
+- `Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.`
+- `Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.`
+
+When responding, ask for or infer these inputs before coding:
+
+- Use case and primary user flows
+- Read-only vs mutating tools
+- Demo vs production target
+- Private/internal use vs public directory submission
+- Backend language and UI stack
+- Auth requirements
+- External API domains for CSP allowlists
+- Hosting target and local dev approach
+- Org ownership/verification readiness (for submission tasks)
+
+## Classify The App Before Choosing Code
+
+Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it.
+
+- `tool-only`
+- `vanilla-widget`
+- `react-widget`
+- `interactive-decoupled`
+- `submission-ready`
+
+Infer the archetype unless a missing detail is truly blocking. Use the archetype to choose:
+
+- whether a UI is needed at all
+- whether to preserve a split `server/` + `web/` layout
+- whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold
+- which validation checks matter most
+- whether `search` and `fetch` should be the default read-only tool surface
+
+Read `references/app-archetypes.md` for the decision rubric.
+
+## Default Starting-Point Order
+
+For greenfield apps, prefer these starting points in order:
+
+1. **Official OpenAI examples** when a close example already matches the requested stack or interaction pattern.
+2. **Version-matched `@modelcontextprotocol/ext-apps` examples** when the user needs a lower-level or more portable MCP Apps baseline.
+3. **`scripts/scaffold_node_ext_apps.mjs`** only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.
+
+Do not generate a large custom scaffold from scratch if a close upstream example already exists.
+Copy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.
+
+## Build Workflow
+
+### 0. Classify The App Archetype
+
+Pick one primary archetype before planning tools or choosing a starting point.
+
+- Prefer a single primary archetype instead of mixing several.
+- If the request is broad, infer the smallest archetype that can still satisfy it.
+- Escalate to `submission-ready` only when the user asks for public launch, directory submission, or review-ready deployment.
+- Call out the chosen archetype in your response so the user can correct it early if needed.
+
+### 1. Plan Tools Before Code
+
+Define the tool surface area from user intents.
+
+- Use one job per tool.
+- Write tool descriptions that start with "Use this when..." behavior cues.
+- Make inputs explicit and machine-friendly (enums, required fields, bounds).
+- Decide whether each tool is data-only, render-only, or both.
+- Set annotations accurately (`readOnlyHint`, `destructiveHint`, `openWorldHint`; add `idempotentHint` when true).
+- If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard `search` and `fetch` tools instead of inventing custom read-only equivalents.
+- For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
+- Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.
+
+Read `references/search-fetch-standard.md` when `search` and `fetch` may be relevant.
+
+### 2. Choose an App Architecture
+
+Choose the simplest structure that fits the goal.
+
+- Use a **minimal demo pattern** for quick prototypes, workshops, or proofs of concept.
+- Use a **decoupled data/render pattern** for production UX so the widget does not re-render on every tool call.
+
+Prefer the decoupled pattern for non-trivial apps:
+
+- Data tools return reusable `structuredContent`.
+- Render tools attach `_meta.ui.resourceUri` and optional `_meta["openai/outputTemplate"]`.
+- Render tool descriptions state prerequisites (for example, "Call `search` first").
+
+### 2a. Start From An Upstream Example When One Fits
+
+Default to upstream examples for greenfield work when they are close to the requested app.
+
+- Check the official OpenAI examples first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.
+- Use `@modelcontextprotocol/ext-apps` examples when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.
+- Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.
+- After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations, `_meta.ui.*`, CSP, URI versioning, and local run instructions.
+- State which example you chose and why in one sentence.
+
+Read `references/upstream-example-workflow.md` for the selection and adaptation rubric.
+
+### 2b. Use the Starter Script When a Low-Dependency Fallback Helps
+
+Use `scripts/scaffold_node_ext_apps.mjs` only when the user wants a quick, greenfield Node starter and a vanilla HTML widget is acceptable, and no upstream example is a better starting point.
+
+- Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.
+- If you choose the script instead of an upstream example, say why the fallback is better for that request.
+- Skip it when a close official example exists, when the user already has an existing app structure, when they need a non-Node stack, when they explicitly want React first, or when they only want a plan/review instead of code.
+- The script generates a minimal `@modelcontextprotocol/ext-apps` server plus a vanilla HTML widget that uses the MCP Apps bridge by default.
+- The generated widget keeps follow-up messaging on the standard `ui/message` bridge and only uses `window.openai` for optional host signals/extensions.
+- After running it, patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.
+
+### 3. Scaffold the MCP Server
+
+Generate a server that:
+
+- Registers a widget resource/template with the MCP Apps UI MIME type (`text/html;profile=mcp-app`) or the SDK constant (`RESOURCE_MIME_TYPE`) when using `@modelcontextprotocol/ext-apps/server`
+- Registers tools with clear names, schemas, titles, and descriptions
+- Returns `structuredContent` (model + widget), `content` (model narration), and `_meta` (widget-only data) intentionally
+- Keeps handlers idempotent or documents non-idempotent behavior explicitly
+- Includes tool status strings (`openai/toolInvocation/*`) when helpful in ChatGPT
+
+Keep `structuredContent` concise. Move large or sensitive widget-only payloads to `_meta`.
+
+### 4. Scaffold the Widget UI
+
+Use the MCP Apps bridge first for portability, then add ChatGPT-specific `window.openai` APIs when they materially improve UX.
+
+- Listen for `ui/notifications/tool-result` (JSON-RPC over `postMessage`)
+- Render from `structuredContent`
+- Use `tools/call` for component-initiated tool calls
+- Use `ui/update-model-context` only when UI state should change what the model sees
+
+Use `window.openai` for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
+
+#### API Surface Guardrails
+
+- Some examples wrap the bridge with an `app` object (for example, `@modelcontextprotocol/ext-apps/react`) and expose helper names like `app.sendMessage()`, `app.callServerTool()`, `app.openLink()`, or host getter methods.
+- Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.
+- For ChatGPT-facing guidance, prefer the current documented surface: `window.openai.callTool(...)`, `window.openai.sendFollowUpMessage(...)`, `window.openai.openExternal(...)`, `window.openai.requestDisplayMode(...)`, and direct globals like `window.openai.theme`, `window.openai.locale`, `window.openai.displayMode`, `window.openai.toolInput`, `window.openai.toolOutput`, `window.openai.toolResponseMetadata`, and `window.openai.widgetState`.
+- If you reference wrapper helpers from repo examples, map them back to the documented `window.openai` or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.
+- Use `references/window-openai-patterns.md` for the wrapper-to-canonical mapping and for React helper extraction patterns.
+
+### 5. Add Resource Metadata and Security
+
+Set resource metadata deliberately on the widget resource/template:
+
+- `_meta.ui.csp` with exact `connectDomains` and `resourceDomains`
+- `_meta.ui.domain` for app submission-ready deployments
+- `_meta.ui.prefersBorder` (or OpenAI compatibility alias when needed)
+- Optional `openai/widgetDescription` to reduce redundant narration
+
+Avoid `frameDomains` unless iframe embeds are core to the product.
+
+### 5a. Enforce A Minimum Working Repo Contract
+
+Every generated repo should satisfy a small, stable contract before you consider it done.
+
+- The repo shape matches the chosen archetype.
+- The MCP server and tools are wired to a reachable `/mcp` endpoint.
+- Tools have clear descriptions, accurate annotations, and UI metadata where needed.
+- Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard `search` and `fetch` tool shapes when relevant.
+- The widget uses the MCP Apps bridge correctly when a UI exists.
+- The repo includes enough scripts or commands for a user to run and check it locally.
+- The response explicitly says what validation was run and what was not run.
+
+Read `references/repo-contract-and-validation.md` for the detailed checklist and validation ladder.
+
+### 6. Validate the Local Loop
+
+Validate against the minimum working repo contract, not just “did files get created.”
+
+- Run the lowest-cost checks first:
+  - static contract review
+  - syntax or compile checks when feasible
+  - local `/mcp` health check when feasible
+- Then move up to runtime checks:
+  - verify tool descriptors and widget rendering in MCP Inspector
+  - test the app in ChatGPT developer mode through HTTPS tunneling
+  - exercise retries and repeated tool calls to confirm idempotent behavior
+  - check widget updates after host events and follow-up tool calls
+- If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.
+
+Read `references/repo-contract-and-validation.md` for the validation ladder.
+
+### 7. Connect and Test in ChatGPT (Developer Mode)
+
+For local development, include explicit ChatGPT setup steps (not just code/run commands).
+
+- Run the MCP server locally on `http://localhost:<port>/mcp`
+- Expose the local server with a public HTTPS tunnel (for example `ngrok http <port>`)
+- Use the tunneled HTTPS URL plus `/mcp` path when connecting from ChatGPT
+- In ChatGPT, enable Developer Mode under **Settings → Apps & Connectors → Advanced settings**
+- In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL
+- Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors
+
+Note: Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
+
+### 8. Plan Production Hosting and Deployment
+
+When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately).
+
+- Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS
+- Preserve low-latency streaming behavior on `/mcp`
+- Configure secrets outside the repo (environment variables / secret manager)
+- Add logging, request latency tracking, and error visibility for tool calls
+- Add basic observability (CPU, memory, request volume) and a troubleshooting path
+- Re-test the hosted endpoint in ChatGPT Developer Mode before submission
+
+### 9. Prepare Submission and Publish (Public Apps Only)
+
+Only include these steps when the user intends a public directory listing.
+
+- Use `apps-sdk/deploy/submission` for the submission flow and `apps-sdk/app-submission-guidelines` for review requirements
+- Keep private/internal apps in Developer Mode instead of submitting
+- Confirm org verification and Owner-role prerequisites before submission work
+- Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured
+- Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info
+- If auth is required, include review-safe demo credentials and test the login path end-to-end
+- Submit for review in the Platform dashboard, monitor review status, and publish only after approval
+
+## Interactive State Guidance
+
+Read `references/interactive-state-sync-patterns.md` when the app has long-lived widget state, repeated interactions, or component-initiated tool calls (for example, games, boards, maps, dashboards, editors).
+
+Use it to choose patterns for:
+
+- State snapshots plus monotonic event tokens (`stateVersion`, `resetCount`, etc.)
+- Idempotent retry-safe handlers
+- `structuredContent` vs `_meta` partitioning
+- MCP Apps bridge-first update flows with optional `window.openai` compatibility
+- Decoupled data/render tool architecture for more complex interactive apps
+
+## Output Expectations
+
+When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
+
+- For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
+
+1. Primary app archetype chosen and why
+2. Tool plan and architecture choice (minimal vs decoupled)
+3. Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why
+4. Doc pages/URLs used from `$openai-docs`
+5. File tree to create or modify
+6. Implementation (server + widget)
+7. Validation performed against the minimum working repo contract
+8. Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)
+9. Deployment/hosting guidance (if requested or implied)
+10. Submission-readiness checklist (for public launch requests)
+11. Risks, gaps, and follow-up improvements
+
+## References
+
+- `references/app-archetypes.md` for classifying requests into a small number of supported app shapes
+- `references/apps-sdk-docs-workflow.md` for doc queries, page targets, and code-generation checklist
+- `references/interactive-state-sync-patterns.md` for reusable patterns for stateful or highly interactive widget apps
+- `references/repo-contract-and-validation.md` for the minimum working repo contract and lightweight validation ladder
+- `references/search-fetch-standard.md` for when and how to default to the standard `search` and `fetch` tools
+- `references/upstream-example-workflow.md` for choosing between official examples, ext-apps examples, and the local fallback scaffold
+- `references/window-openai-patterns.md` for ChatGPT-specific extensions, wrapper API translation, and React helper patterns
+- `scripts/scaffold_node_ext_apps.mjs` for a minimal Node + `@modelcontextprotocol/ext-apps` fallback starter scaffold

package/skills/chatgpt-apps/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "ChatGPT Apps"
+  short_description: "Build and scaffold ChatGPT apps"
+  default_prompt: "Use $chatgpt-apps to classify the app archetype first, fetch current OpenAI Apps SDK docs before generating code, default to the standard `search` and `fetch` tools when the app is connector-like or sync-oriented, adapt the closest upstream example when one fits, and only fall back to the local Node scaffold for minimal `@modelcontextprotocol/ext-apps` starters. Produce a working repo shape, then report what validation was actually run."
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "openaiDeveloperDocs"
+      description: "OpenAI developer docs MCP server for current Apps SDK guidance"
+      transport: "streamable_http"
+      url: "https://developers.openai.com/mcp"
+policy:
+  allow_implicit_invocation: true

package/skills/chatgpt-apps/references/app-archetypes.md

@@ -0,0 +1,132 @@
+# App Archetypes
+
+Load this reference before choosing a starting point for a new ChatGPT app. The goal is to keep the skill inside a small number of supported app shapes instead of inventing a custom structure for every prompt.
+
+## Rule
+
+Choose one primary archetype per request and state it.
+
+Do not combine several archetypes unless the user explicitly asks for a hybrid app and the extra complexity is necessary.
+
+## Archetypes
+
+### `tool-only`
+
+Use when:
+
+- The user does not need an in-ChatGPT UI
+- The task is mainly search, fetch, retrieval, or background actions
+
+Default shape:
+
+- MCP server only
+
+Best starting point:
+
+- Official docs and MCP server examples
+
+Validation emphasis:
+
+- `/mcp` route works
+- tool schemas and annotations are correct
+- no unnecessary UI resource is registered
+- if the app is connector-like or sync-oriented, `search` and `fetch` should be the default read-only tools
+
+### `vanilla-widget`
+
+Use when:
+
+- The user wants a small demo, workshop starter, or simple inline widget
+- A single HTML widget is enough
+- The user wants the fastest path to a working repo
+
+Default shape:
+
+- Root-level server plus `public/` widget assets
+
+Best starting point:
+
+- Apps SDK quickstart first
+- Local fallback scaffold if the quickstart is not a good fit
+
+Validation emphasis:
+
+- bridge initialization
+- `ui/notifications/tool-result`
+- `tools/call` only when the widget is interactive
+
+### `react-widget`
+
+Use when:
+
+- The user wants a polished UI
+- The UI is clearly component-based
+- The user mentions React, TypeScript frontend tooling, or richer design requirements
+
+Default shape:
+
+- Split `server/` + `web/` layout when the example already uses it
+
+Best starting point:
+
+- Official OpenAI examples
+
+Validation emphasis:
+
+- build output is wired into the server correctly
+- bundle references resolve
+- widget renders from `structuredContent`
+
+### `interactive-decoupled`
+
+Use when:
+
+- The app has repeated user interaction
+- The widget should stay mounted while tools are called repeatedly
+- The app is a board, map, editor, game, dashboard, or other stateful experience
+
+Default shape:
+
+- Split `server/` + `web/`
+- data tools plus render tools
+
+Best starting point:
+
+- Official OpenAI examples plus `references/interactive-state-sync-patterns.md`
+
+Validation emphasis:
+
+- tool retries are safe
+- widget does not remount unnecessarily
+- state sync is intentional
+- UI tool calls work independently of model reruns
+
+### `submission-ready`
+
+Use when:
+
+- The user asks for public launch, review readiness, or directory submission
+
+Default shape:
+
+- Smallest viable repo that still includes deployment and review requirements
+
+Best starting point:
+
+- Closest official example that matches the requested stack
+
+Validation emphasis:
+
+- `_meta.ui.domain`
+- accurate CSP
+- auth and review-safe flows
+- submission prerequisites and artifacts
+
+## Selection Heuristic
+
+- If the prompt does not mention a UI, choose `tool-only`.
+- If the prompt is about a knowledge source, sync app, connector-like integration, or deep research, strongly prefer `tool-only` plus the standard `search` and `fetch` tools unless the user clearly needs a widget.
+- If the prompt asks for a simple demo or starter, choose `vanilla-widget`.
+- If the prompt asks for a polished UI or React, choose `react-widget`.
+- If the prompt implies long-lived client state or repeated interaction, choose `interactive-decoupled`.
+- Only choose `submission-ready` when the user explicitly asks for launch or review-readiness work.