README.md

# FormHug OpenAI plugin

This directory contains the source of the existing FormHug ChatGPT plugin.
Release `2.0.1` adds an explicit MCP connection and a portable manifest while
retaining the published plugin identity, listing text, and starter prompts.

## Package layout

```text
openai/
  plugin.json                 # Agent Plugins 1.0 manifest
  mcp.json                    # Remote FormHug MCP connection
  .codex-plugin/plugin.json   # Compatibility manifest for older clients
  assets/icon.png             # 512 × 512 FormHug app and composer icon
  skills/
    formhug-create-form/
    formhug-create-quiz/
    formhug-improve-form/
    formhug-analyze-responses/
```

Keep identity, version, and interface metadata synchronized between the two
manifests. The portable manifest discovers `skills/` and `mcp.json` at their
fixed locations; the compatibility manifest references them explicitly.
The `formhug` server key matches every skill's `agents/openai.yaml` dependency.

Both manifests reference `assets/icon.png` through `logo` and `composerIcon`.
The PNG reuses the existing FormHug brand icon from
`next-app-main/src/assets/images/icon.png`; include it in every exported ZIP.

## MCP connection

- Production endpoint: `https://formhug.ai/mcp`.
- Transport: Streamable HTTP (`streamable-http` in `mcp.json`,
  `streamable_http` in skill dependency metadata).
- Authentication: the host completes FormHug OAuth authorization with PKCE
  S256. No client secret, access token, or static Authorization header belongs
  in this package. OAuth client secrets are Worker deployment secrets.
- Discovery: `https://formhug.ai/.well-known/oauth-protected-resource/mcp`
  and `https://formhug.ai/.well-known/oauth-authorization-server`.
- UAT endpoint: `https://uat.formhug.ai/mcp`. Use it only in a separate test
  copy, updating both `mcp.json` and all skill dependency URLs together.

The endpoint and discovery routes are configured in the repository's
`wrangler.jsonc`; routing and OAuth are implemented in `src/index.ts`.
Tools and references come from the remote server, so the plugin does not bundle
the Worker runtime or duplicate its tool schemas. Installing the package does
not deploy the Worker.

The server provides form and field management, settings, themes, conditional
rules, folders, entries, uploads, webhooks, public lookup pages, and account
information. The four packaged skills guide form creation, scored quizzes and
assessments, existing-form improvements, and response analysis.

Read `formhug://guide` before a workflow. Then read the task-specific resource,
such as `formhug://field-types`, `formhug://themes`, `formhug://field-rules`,
`formhug://entries-filter`, or `formhug://entry-values`. Hosts without direct
resource access can call `read_reference` with the same URI. The authoritative
reference registry is `src/resources/index.ts`.

## Export and verify

Run these commands from the repository root. The staging directory uses the
existing manifest name to preserve the published identity. The archive includes
hidden compatibility files and excludes macOS metadata.

```bash
staging_dir=$(mktemp -d)
plugin_name=$(node -p "require('./published-plugins/openai/plugin.json').name")
mkdir "$staging_dir/$plugin_name"
cp -R published-plugins/openai/. "$staging_dir/$plugin_name/"
archive_path="$PWD/published-plugins/formhug-openai-2.0.1.zip"
(cd "$staging_dir" && zip -r "$archive_path" "$plugin_name" -x '*/.DS_Store' '*/__MACOSX/*')
unzip -l "$archive_path"
```

Validate `plugin.json` and `mcp.json` against their declared schemas, check that
each skill's directory matches its frontmatter name, and verify that dependency
names and URLs match `mcp.json`. Before publishing, connect the plugin in the
intended host, complete OAuth, and call `read_reference` for `formhug://guide`
plus a read-only discovery tool such as `list_forms`. Check form-preview UI in
the host when preview behavior is part of the release. Do not create real test
submissions merely to validate installation.

Source changes or an exported ZIP do not update the published plugin. Use the
existing plugin's release flow and preserve its sharing and permissions.