@synapta/skills 0.1.0 → 0.1.2

package/skills/apps-sdk-builder/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.

package/skills/apps-sdk-builder/references/apps-sdk-docs-workflow.md

@@ -0,0 +1,135 @@
+# Apps SDK Docs Workflow
+
+Use this reference to keep code generation aligned with current OpenAI Apps SDK docs.
+
+## Always Fetch These Pages (Baseline)
+
+- `https://developers.openai.com/apps-sdk/build/mcp-server/`
+- `https://developers.openai.com/apps-sdk/build/chatgpt-ui/`
+- `https://developers.openai.com/apps-sdk/build/examples/`
+- `https://developers.openai.com/apps-sdk/plan/tools/`
+- `https://developers.openai.com/apps-sdk/reference/`
+
+## Fetch Conditionally (Greenfield / First Pass)
+
+- `https://developers.openai.com/apps-sdk/quickstart/` for first implementation scaffolds and happy-path wiring
+- `https://developers.openai.com/apps-sdk/deploy/` when the task includes local ChatGPT testing via tunnel, hosting, or production deployment planning
+- `https://developers.openai.com/apps-sdk/deploy/submission/` when the task includes public launch, app review, or publishing steps
+- `https://developers.openai.com/apps-sdk/app-submission-guidelines/` when the task includes submission readiness, policy/reliability checks, or review-risk reduction
+
+## Suggested `openai-docs` / MCP Queries
+
+Use focused searches before fetching:
+
+- `ChatGPT Apps SDK build MCP server register resource template resourceUri outputTemplate`
+- `ChatGPT Apps SDK build ChatGPT UI MCP Apps bridge ui/notifications/tool-result`
+- `ChatGPT Apps SDK examples React widget upload modal Pizzaz`
+- `Apps SDK define tools annotations readOnlyHint destructiveHint openWorldHint`
+- `Apps SDK reference tool descriptor _meta ui.resourceUri openai/outputTemplate`
+- `ChatGPT Apps SDK quickstart build web component tools/call`
+- `ChatGPT app company knowledge compatibility search fetch tools`
+- `platform MCP search tool fetch tool schema`
+- `ChatGPT Apps SDK deploy app local development tunnel ngrok refresh connector`
+- `ChatGPT Apps SDK submit app review prerequisites app submission guidelines`
+
+## Docs-Derived Checklist (Current Guidance)
+
+### Archetype / Shape
+
+- Classify the request into one primary app archetype before choosing examples or scaffolds
+- Keep the repo shape consistent with that archetype instead of inventing a new structure for each prompt
+
+### Server
+
+- Register the widget resource/template with the MCP Apps UI MIME type (`text/html;profile=mcp-app`) or `RESOURCE_MIME_TYPE` when using `@modelcontextprotocol/ext-apps/server`
+- Version template URIs when widget HTML or JS or CSS changes in a breaking way (treat URI as cache key)
+- Set `_meta.ui.resourceUri` on render tools; optionally mirror `_meta["openai/outputTemplate"]` for ChatGPT compatibility
+- Design tool handlers to be idempotent because the model may retry calls
+- Keep `structuredContent` concise and move widget-only payloads to `_meta`
+
+### Tool Design
+
+- Plan one user intent per tool
+- Use action-oriented names and precise descriptions
+- Set tool impact hints accurately (`readOnlyHint`, `destructiveHint`, `openWorldHint`)
+- Split data and render tools so that the model can fetch the data and look at it before choosing to render the widget UI or not
+- Make the widget input a list of unique identifiers (e.g. `propertyIds` for a render property map widget that takes IDs returned from the fetch properties nearby tool) if you want to make sure the widget only renders 1p data; make the widget input semantically relevant if you want to allow the model to render the widget with generated data (e.g. `questionAndAnswerPairs` for a flashcards widget)
+- For connector-like, data-only, sync-oriented, or company-knowledge-style apps, prefer the standard `search` and `fetch` tools by default
+
+### UI
+
+- Prefer the MCP Apps bridge (`ui/*` notifications + `tools/call`) for new apps
+- Prefer `ui/message` for follow-up messaging in baseline examples; treat `window.openai.sendFollowUpMessage` as optional ChatGPT-specific compatibility
+- Treat `window.openai` as compatibility plus optional ChatGPT extensions
+- Render from `structuredContent` and treat host-delivered data as untrusted input
+- Use `ui/update-model-context` only for UI state the model should reason about
+
+### Starting Point Selection
+
+- Check `apps-sdk/build/examples` and the official examples repo before generating a greenfield scaffold from scratch
+- Prefer the smallest upstream example that matches the requested stack and interaction pattern
+- Use the local fallback scaffold only when upstream examples are a poor fit or undesirable for the request
+
+### Resource Metadata / Security
+
+- Set `_meta.ui.csp.connectDomains` and `_meta.ui.csp.resourceDomains` exactly
+- Avoid `frameDomains` unless iframe embedding is central to the experience
+- Set `_meta.ui.domain` for submission-ready apps
+- Always set `openai/widgetDescription` to inform the model what the widget is to be used for
+
+### Developer Mode / Local Testing
+
+- Run the MCP server locally on `http://localhost:<port>/mcp`
+- Expose it with a public HTTPS tunnel for ChatGPT access during development
+- Use the public URL + `/mcp` when adding the app in ChatGPT settings
+- Include ChatGPT Developer Mode setup and app creation steps in implementation handoff
+- Remind users to refresh the app after MCP tool/metadata changes
+- Note terminology differences when relevant: some docs/screenshots may still say "connector" while product UI uses "app"
+
+### Validation
+
+- Validate against a minimum working repo contract, not just file creation
+- Run the cheapest useful syntax or compile check first
+- If feasible, confirm the local `/mcp` route responds before calling the result “working”
+- If you cannot run a deeper check, say so explicitly
+- If the app is connector-like or sync-oriented, verify the `search` and `fetch` tool shapes against the standard
+
+### Production Hosting / Deploy
+
+- Prefer a stable public HTTPS endpoint with reliable TLS and low-latency streaming `/mcp`
+- Document platform-specific secrets handling and environment variables
+- Include logging/metrics expectations for debugging production tool calls
+- Re-test the hosted endpoint in ChatGPT Developer Mode before submission
+
+### Submission / Review
+
+- Read `deploy/submission` and `app-submission-guidelines` together (process + policy requirements)
+- Check org verification and Owner-role prerequisites before generating submission steps
+- Ensure the endpoint is public production infrastructure (not localhost/tunnel/testing URLs)
+- Ensure CSP is defined and accurate for submission
+- Prepare submission artifacts (metadata, screenshots, privacy policy/support contacts, test prompts/responses)
+- If auth is required, prepare review-safe demo credentials and validate them outside internal networks
+
+## Generation Pattern
+
+1. Classify the app archetype.
+2. Fetch docs with `$openai-docs`.
+3. Check official examples before inventing a scaffold from scratch.
+4. Summarize relevant constraints and metadata keys.
+5. Propose tool plan and architecture.
+6. Adapt the closest example or use the local fallback scaffold.
+7. Generate or patch the server scaffold.
+8. Generate or patch the widget scaffold.
+9. Validate the repo against the minimum working contract.
+10. Add local run + tunnel + ChatGPT Developer Mode app setup instructions.
+11. Add hosting/deployment guidance when the task implies go-live.
+12. Add submission/readiness steps when the user intends public distribution.
+13. Call out compatibility aliases vs MCP Apps standard fields.
+
+## Starter Scaffold Script
+
+- Use `./scripts/scaffold_node_ext_apps.mjs <output-dir> --app-name <name>` only when the user wants a greenfield Node + `@modelcontextprotocol/ext-apps` starter and no upstream example is the better fit.
+- If the file is not executable in the current environment, fall back to `node scripts/scaffold_node_ext_apps.mjs <output-dir> --app-name <name>`.
+- The script generates `package.json`, `tsconfig.json`, `public/widget.html`, and `src/server.ts`.
+- It intentionally uses the MCP Apps bridge by default, keeps follow-up messaging on `ui/message`, and limits `window.openai` to optional host signals/extensions.
+- After generation, compare the output against the docs you fetched and adjust package versions, metadata, transport details, or URI/versioning if the docs changed.

package/skills/apps-sdk-builder/references/interactive-state-sync-patterns.md

@@ -0,0 +1,113 @@
+# Interactive State Sync Patterns
+
+Use this reference when building ChatGPT apps with long-lived widget state, repeated interactions, or component-initiated tool calls (for example: games, boards, maps, dashboards, editors, or realtime-ish UIs).
+
+Do not load this file for simple read-only render apps unless state sync behavior is part of the task.
+
+## When This Reference Helps
+
+Read this file when the app needs one or more of these patterns:
+
+- Repeated actions that may return similar data (retry, refresh, reset, reroll)
+- UI controls that trigger tool calls after the initial render
+- Local widget behavior that should also work outside ChatGPT during development
+- Multiple tool calls updating one mounted widget over time
+- Clear separation between model-visible state and widget-only state
+
+## Reusable Patterns
+
+### 1. Snapshot + Event Token
+
+Return a stable state snapshot in `structuredContent` and add a monotonic event token for repeated actions that may not change other fields.
+
+Examples:
+
+- `stateVersion`
+- `refreshCount`
+- `resetCount`
+- `lastMutationId`
+
+Use this when the widget must detect "same shape, new event" updates reliably.
+
+### 2. Intent-Focused Tool Surface
+
+Prefer small, explicit tools that map to user-visible actions or data operations.
+
+- Keep names action-oriented
+- Use enums and bounded schemas where possible
+- Avoid kitchen-sink tools that mix unrelated reads and writes
+
+This improves model tool selection and reduces malformed calls.
+
+### 3. Idempotent Handlers (or Explicitly Non-Idempotent)
+
+Design handlers to tolerate retries. If a tool is not idempotent, make the side effect explicit and confirm intent in the flow.
+
+- Reads and pure transforms should usually be idempotent
+- Writes should include clear impact hints and current-turn confirmation where needed
+- Repeated calls with the same input should not corrupt widget state
+
+### 4. `structuredContent` / `_meta` Partitioning
+
+Partition payloads intentionally:
+
+- `structuredContent`: concise model-visible state the widget also uses
+- `content`: short narration/status text
+- `_meta`: large maps, caches, or sensitive widget-only hydration data
+
+Keep `structuredContent` small enough for follow-up reasoning and chaining.
+
+### 5. MCP Apps Bridge First, `window.openai` Second
+
+For new scaffolds:
+
+- Prefer MCP Apps bridge notifications and `tools/call` (portable across hosts)
+- Use `window.openai` as a compatibility layer plus optional ChatGPT extensions
+
+This keeps the app portable while still enabling ChatGPT-specific capabilities when helpful.
+
+### 6. Component-Initiated Tool Calls Without Remounting
+
+For interactive widgets, allow the UI to call data/action tools directly and update the existing widget state instead of forcing a full re-render/remount every time.
+
+This is especially useful for:
+
+- Refresh
+- Retry
+- Rerun
+- Toggle/filter actions
+- Incremental interactions inside one widget session
+
+### 7. Standalone / No-Host Fallback Mode
+
+When feasible, make the widget usable without ChatGPT during development:
+
+- If host APIs are unavailable, apply local state directly
+- Preserve basic interactions in a normal browser
+
+This speeds up front-end iteration and reduces dependence on connector setup for every UI tweak.
+
+### 8. Decouple Data Tools from Render Tools (When Complexity Grows)
+
+Use separate data and render tools when the app has multi-step reasoning or frequent updates.
+
+- Data tools fetch/compute/mutate and return reusable `structuredContent`
+- Render tools attach the widget template and focus on presentation
+
+This reduces unnecessary remounts and gives the model a chance to refine data before rendering.
+
+## Common Anti-Patterns
+
+- Putting large widget-only blobs into `structuredContent`
+- Attaching a widget template to every tool when only one render tool needs it
+- Using hidden client-side state as the source of truth for critical actions
+- Depending only on `window.openai` APIs for baseline app behavior
+- Using ambiguous tool names that do not match user intent
+
+## Example App Types That Benefit From These Patterns
+
+- Multiplayer or turn-based games
+- Collaborative boards / task views
+- Maps with filters and repeated searches
+- Dashboards with refresh and drill-down actions
+- Editors or builders with iterative tool calls

package/skills/apps-sdk-builder/references/repo-contract-and-validation.md

@@ -0,0 +1,93 @@
+# Repo Contract And Validation
+
+Load this reference when scaffolding or reviewing a generated ChatGPT app repo.
+
+The goal is not “files were created.” The goal is “the repo is plausibly runnable and follows a stable working-app contract.”
+
+## Minimum Working Repo Contract
+
+Every generated repo should satisfy the relevant parts of this contract.
+
+### 1. Shape
+
+- The repo shape matches the chosen archetype.
+- The repo structure is simple enough that a user can identify where the server and widget live.
+
+### 2. Server
+
+- There is a clear MCP server entry point.
+- The server exposes `/mcp`.
+- The server registers tools intentionally.
+- If a UI exists, the server registers a resource/template with the MCP Apps UI MIME type.
+
+### 3. Tools
+
+- Each tool maps to one user intent.
+- Descriptions help the model choose the tool.
+- Required annotations are present and accurate.
+- UI-linked tools use `_meta.ui.resourceUri`.
+- `_meta["openai/outputTemplate"]` is treated as optional compatibility, not the primary contract.
+- When the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, it implements standard `search` and `fetch` tools instead of custom substitutes.
+
+### 4. Widget
+
+- The widget initializes the MCP Apps bridge when needed.
+- The widget can receive `ui/notifications/tool-result`.
+- The widget renders from `structuredContent`.
+- Interactive widgets use `tools/call`.
+- Baseline follow-up messaging uses `ui/message`.
+- `window.openai` is optional and additive.
+
+### 5. Local Developer Experience
+
+- There is a clear way to start the app locally.
+- There is at least one low-cost check command when the stack supports it.
+- The response explains how to connect the app in ChatGPT Developer Mode when relevant.
+
+## Validation Ladder
+
+Run the highest level you can without overfitting to a single stack.
+
+### Level 0: Static contract review
+
+Check for:
+
+- chosen archetype is sensible
+- repo shape matches archetype
+- `/mcp` route is present
+- tool/resource/widget responsibilities are coherent
+- if the app is connector-like or sync-oriented, `search` and `fetch` are present with the expected standard shape
+
+### Level 1: Syntax or compile checks
+
+Use the stack-appropriate cheapest check available, for example:
+
+- Python syntax check
+- TypeScript compile check
+- framework-specific lint or build sanity check if already installed
+
+### Level 2: Local runtime sanity
+
+If feasible:
+
+- start the server
+- confirm the health route or `/mcp` endpoint responds
+
+### Level 3: Host loop validation
+
+If feasible:
+
+- inspect with MCP Inspector
+- test through ChatGPT Developer Mode
+- confirm widget updates after tool results
+
+## Reporting Rule
+
+Always say which validation level was reached and what was not run.
+
+That makes the skill more reliable because it separates:
+
+- “repo shape looks right”
+- “syntax is valid”
+- “server starts”
+- “host integration was actually exercised”

package/skills/apps-sdk-builder/references/search-fetch-standard.md

@@ -0,0 +1,67 @@
+# Search And Fetch Standard
+
+Load this reference when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research.
+
+## Default Rule
+
+If the app is primarily a read-only knowledge source, do not invent custom equivalents to `search` and `fetch`.
+
+Default to implementing the standard `search` and `fetch` tools exactly, then add other tools only if the use case clearly needs them.
+
+## When This Applies
+
+Use the standard by default when the request is about:
+
+- a data-only app
+- a sync app
+- a company knowledge source
+- deep research compatibility
+- a connector-like integration over documents, tickets, wiki pages, CRM records, or similar read-only data
+
+## Tool Requirements
+
+### `search`
+
+- Read-only tool
+- Takes a single query string
+- Returns exactly one MCP content item with `type: "text"`
+- That text is a JSON-encoded object with:
+  - `results`
+  - each result has `id`, `title`, and `url`
+
+### `fetch`
+
+- Read-only tool
+- Takes a single document/item id string
+- Returns exactly one MCP content item with `type: "text"`
+- That text is a JSON-encoded object with:
+  - `id`
+  - `title`
+  - `text`
+  - `url`
+  - optional `metadata`
+
+## Implementation Rules
+
+- Match the schema exactly when the app is intended for company knowledge or deep research compatibility.
+- Use canonical `url` values for citations.
+- Mark these tools as read-only.
+- Prefer these names exactly: `search` and `fetch`.
+- If you add other read-only tools, they should complement the standard rather than replace it.
+
+## Validation Checks
+
+When `search` and `fetch` are relevant, verify:
+
+- both tools exist
+- they are read-only
+- their input shapes match the standard
+- their returned payloads are wrapped as one `content` item with JSON-encoded `text`
+- result URLs are canonical enough for citation use
+
+## Source
+
+This standard is described in:
+
+- `https://developers.openai.com/apps-sdk/build/mcp-server/#company-knowledge-compatibility`
+- `https://platform.openai.com/docs/mcp`

package/skills/apps-sdk-builder/references/upstream-example-workflow.md

@@ -0,0 +1,79 @@
+# Upstream Example Workflow
+
+Load this reference when starting a greenfield ChatGPT app or when deciding whether to adapt an upstream example or use the local fallback scaffold.
+
+## Default Order
+
+Prefer these starting points in order:
+
+1. Official OpenAI Apps SDK examples
+2. Version-matched `@modelcontextprotocol/ext-apps` examples
+3. Local `scripts/scaffold_node_ext_apps.mjs` fallback
+
+This keeps the skill aligned with current docs and maintained example code while still preserving a low-dependency fallback when examples are not a good fit.
+
+## Choose The Right Source
+
+### 1. Official OpenAI examples
+
+Prefer these when:
+
+- The app is clearly ChatGPT-facing
+- The user wants a polished UI or React component
+- The task involves file upload, modal flows, display-mode changes, or other ChatGPT extensions
+- The docs/examples page already shows a similar interaction pattern
+
+Typical sources:
+
+- `https://developers.openai.com/apps-sdk/build/examples/`
+- `https://github.com/openai/openai-apps-sdk-examples`
+- `https://developers.openai.com/apps-sdk/quickstart/` for the smallest vanilla baseline
+
+### 2. `@modelcontextprotocol/ext-apps` examples
+
+Prefer these when:
+
+- The user needs a lower-level MCP Apps baseline
+- Portability across MCP Apps-compatible hosts matters more than ChatGPT-specific polish
+- You want version-matched examples close to the installed `@modelcontextprotocol/ext-apps` package shape
+
+This follows the same basic idea as the upstream `create-mcp-app` skill: use maintained examples as the starting point, then adapt them.
+
+Typical examples from upstream flows:
+
+- `examples/demo-vanilla-html`
+- `examples/demo-react-simple`
+- `examples/demo-connectors-api`
+
+### 3. Local fallback scaffold
+
+Use `scripts/scaffold_node_ext_apps.mjs` when:
+
+- No close upstream example exists
+- The user wants a tiny Node + vanilla HTML starter
+- Network/example retrieval is undesirable
+- You need a throwaway starter to patch quickly during a live coding task
+
+Do not prefer the local scaffold just because it is available. It is the fallback, not the default.
+
+## Adaptation Rules
+
+- Copy the smallest matching example, not the entire showcase app.
+- Remove unrelated demo tools, assets, and routes immediately.
+- Keep the upstream file structure when it is already clean and docs-aligned.
+- Reconcile the copied example with the current docs before finishing:
+  - tool names and descriptions
+  - annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint` when true)
+  - `_meta.ui.resourceUri` and optional `_meta["openai/outputTemplate"]`
+  - resource `_meta.ui.csp`, `_meta.ui.domain`, and `openai/widgetDescription`
+  - URI versioning for template changes
+  - local run/test instructions
+- State which example you chose and why.
+- If you rely on upstream code, note the source repo and branch/tag/commit when practical; avoid silently depending on a floating example shape for long-lived work.
+
+## Minimal Selection Heuristic
+
+- If the user asks for **React + polished UI**, start with official OpenAI examples.
+- If the user asks for **vanilla HTML + tiny demo**, start with the quickstart example; use the local fallback scaffold only if the quickstart is still too opinionated or unavailable.
+- If the user asks for **portable MCP Apps wiring**, start with `@modelcontextprotocol/ext-apps` examples.
+- If the user already has an app, adapt their code directly instead of importing a new example.