🍱 Add Spire plugin artwork and icon metadata
This commit is contained in:
@@ -0,0 +1,110 @@
|
||||
# Codex plugin icons and metadata in Reliquary
|
||||
|
||||
Date: 2026-10-02
|
||||
|
||||
## Answer for this repository
|
||||
|
||||
Reliquary is a Git repository at `git.g4b.org:dirigence/reliquary`. Codex can register that Git repository as the **marketplace source**. Inside its `.agents/plugins/marketplace.json`, each plugin has `"source": "local"` and a path such as `./plugins/spire`. Here, `local` means *relative to the fetched marketplace repository*, not that users must install the marketplace from a local disk checkout. These are two different source levels. The marketplace file makes Spire and Tome discoverable, but does not define their icons. [OpenAI Docs: marketplace sources and metadata](https://developers.openai.com/plugins/build/plugins)
|
||||
|
||||
At the initial investigation, neither Spire nor Tome had an `interface` object or image assets, so the images in the screenshot were application fallbacks. Spire now has bundled artwork and explicit image paths; Tome still has no image assets or `interface` object. OpenAI's public documentation specifies how to supply an icon, but does not document the fallback-selection rule that produced the star for Spire and the document for Tome. Do not depend on those particular fallback images.
|
||||
|
||||
## Set a deliberate icon
|
||||
|
||||
For Reliquary's current Codex compatibility manifests, put image paths in the plugin's `.codex-plugin/plugin.json`, under `interface`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "spire",
|
||||
"version": "0.1.1",
|
||||
"description": "Spire — an agent orchestration system for structured development.",
|
||||
"author": { "name": "Gabor Körber", "email": "gab@g4b.org" },
|
||||
"skills": "./skills/",
|
||||
"interface": {
|
||||
"displayName": "Spire",
|
||||
"shortDescription": "Structured agent workflows",
|
||||
"longDescription": "Skills for session coordination, research, workpad use, and implementation.",
|
||||
"developerName": "Gabor Körber",
|
||||
"category": "Productivity",
|
||||
"capabilities": ["Skills", "Agents"],
|
||||
"logo": "./assets/spire_logo512.png",
|
||||
"composerIcon": "./assets/spire_icon512.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Spire now stores the detailed logo at `plugins/spire/assets/spire_logo512.png`, the simpler composer icon at `plugins/spire/assets/spire_icon512.png`, and a 128 px emoji image for the READMEs at `plugins/spire/assets/spire_logo128_emoji.png`. Apply the same pattern under `plugins/tome/` when Tome artwork is available. Paths begin with `./` and resolve from the **plugin root** (`plugins/spire/`), even though the manifest is in `.codex-plugin/`. The images must be included in the Git repository. `logo` is the primary listing image; `composerIcon` is the icon used in the composer. The same image can serve both fields if suitable. Optional `logoDark` and `composerIconDark` point to dark-theme variants. [OpenAI Docs: manifest path rules](https://developers.openai.com/plugins/build/plugins), [OpenAI Docs: listing metadata](https://developers.openai.com/plugins/deploy/submission)
|
||||
|
||||
This is the source-independent part of the solution: the manifest and image files travel **together inside the plugin package**. The same `./assets/spire_logo512.png` reference resolves when Codex obtains the marketplace from `git.g4b.org`, another Git remote, a local checkout, or a copied package. No icon path should refer to `G:\dev\...`, a Git web URL, a user's home directory, or a folder outside the plugin root. Each consuming client must still refresh or reinstall its cached package after an update; source-independent paths do not imply instant updates.
|
||||
|
||||
Supported formats are PNG, JPEG, WebP, and SVG. Images must be square and at least 48 × 48 pixels, with a maximum file size of 5 MiB. Raster images cannot exceed 4096 pixels on either side. SVGs need a square numeric `viewBox` or square numeric dimensions of at least 48 × 48; dimensions cannot use units or percentages. `screenshots` is an optional array of paths to additional images. These are package-validation rules for distribution; for consistent behavior, follow them for this marketplace too. [OpenAI Docs: image requirements](https://developers.openai.com/plugins/deploy/submission), [OpenAI Docs: image validation errors](https://developers.openai.com/plugins/deploy/submission-errors)
|
||||
|
||||
Tome's minimal manifest still lacks several fields required by **Codex package validation for distribution**, including `interface`, `logo`, and `composerIcon`. Its appearance in this personal marketplace does not prove it would pass public submission validation. Spire has these fields now, although no public submission validation was run. [OpenAI Docs: package and listing requirements](https://developers.openai.com/plugins/deploy/submission)
|
||||
|
||||
## Other settings you can set
|
||||
|
||||
### Plugin manifest: identity and components
|
||||
|
||||
| Field | Purpose |
|
||||
| --- | --- |
|
||||
| `name` | Stable plugin identifier; keep it distinct from the display name. |
|
||||
| `version` | Package version. Use an explicit semantic version for distribution and updates. |
|
||||
| `description` | Package summary. |
|
||||
| `author` | Publisher name, optionally email and HTTPS URL. |
|
||||
| `homepage`, `repository`, `license`, `keywords` | Optional project and discovery metadata. `homepage` does not automatically populate the listing website link. |
|
||||
| `skills` | In the Codex compatibility format, a relative skills directory such as `./skills/`. Spire and Tome should declare this if they intend their bundled skills to be loaded in that format. |
|
||||
| `mcpServers` | In the Codex compatibility format, a path to bundled MCP server configuration if the plugin includes an MCP server. |
|
||||
| `apps` | Mapping to registered MCP apps via `.app.json`, when relevant. |
|
||||
| `hooks` | Optional lifecycle hook configuration; hook scripts need user trust and must exist in the execution environment. |
|
||||
|
||||
Tome's manifest omits `skills`; Spire and several other Reliquary plugins now explicitly include `"skills": "./skills/"`. The official compatibility-format field reference says to use `skills` for Codex packages with skills. This report does not test whether a particular installed copy auto-discovers Tome's skills without that declaration. [OpenAI Docs: package components](https://developers.openai.com/plugins/deploy/submission), [OpenAI Docs: hooks and MCP servers](https://developers.openai.com/plugins/build/plugins)
|
||||
|
||||
### `interface`: what people see
|
||||
|
||||
| Field | Purpose |
|
||||
| --- | --- |
|
||||
| `displayName` | Name shown to users. |
|
||||
| `shortDescription` | Short subtitle beside or below the name. |
|
||||
| `longDescription` | Fuller explanation of tasks, audience, and limitations. |
|
||||
| `developerName` | Publisher label. |
|
||||
| `category` | Directory category. |
|
||||
| `capabilities` | Labels describing what the plugin provides, such as `Skills`. |
|
||||
| `websiteURL`, `supportURL`, `privacyPolicyURL`, `termsOfServiceURL` | Listing and support links; the four URLs are required for public review of an attached MCP app. |
|
||||
| `defaultPrompt` | One starter prompt or an array of up to three. |
|
||||
| `brandColor`, `brandColorDark` | Light and dark theme accent colors. |
|
||||
| `logo`, `logoDark` | Primary listing image and optional dark variant. |
|
||||
| `composerIcon`, `composerIconDark` | Composer icon and optional dark variant. |
|
||||
| `screenshots` | Optional image paths for the listing. |
|
||||
|
||||
For public submission, the documented text limits include 30 characters each for `displayName` and `shortDescription`, 4000 for `longDescription`, and 80 for `developerName`; `defaultPrompt` allows up to three prompts of 128 characters each. The public format requires `displayName`, both descriptions, `developerName`, `category`, `capabilities`, `logo`, and `composerIcon` for Codex packages. Local or private marketplace display may tolerate incomplete metadata, as the current screenshot demonstrates. [OpenAI Docs: listing fields and limits](https://developers.openai.com/plugins/deploy/submission)
|
||||
|
||||
### Marketplace catalog: availability, not artwork
|
||||
|
||||
Reliquary's `.agents/plugins/marketplace.json` controls the marketplace title (`interface.displayName`), plugin ordering, plugin folder paths, `category`, and install policy. Each entry can set `policy.installation` (for example `AVAILABLE`, `INSTALLED_BY_DEFAULT`, or `NOT_AVAILABLE`) and `policy.authentication` (authentication on install or first use). The catalog can point to plugin folders within the Git marketplace checkout via `source: "local"`; it can also point to separate Git-backed plugin sources using `source: "url"` or `source: "git-subdir"`. It does not carry `logo` or `composerIcon` for each plugin. [OpenAI Docs: marketplace metadata](https://developers.openai.com/plugins/build/plugins)
|
||||
|
||||
### Portable format and public publication
|
||||
|
||||
OpenAI now recommends a root `plugin.json` for portable Agent Plugins packages. In that format, package identity stays at the root, components use `skills/` and `mcp.json`, and OpenAI presentation fields go under `extensions.com.openai.interface`. The existing `.codex-plugin/plugin.json` remains a supported compatibility fallback. If a root `plugin.json` has an `extensions.com.openai` object, OpenAI uses that object for OpenAI-specific settings **instead of** the compatibility manifest; the two are not merged. If Reliquary adopts the portable format later, move icon and interface metadata together so a stale compatibility manifest does not mislead maintainers. [OpenAI Docs: portable and compatibility manifests](https://developers.openai.com/plugins/build/plugins)
|
||||
|
||||
For public submissions, additional `extensions.com.openai` settings include `onboardingSkill`, review test cases and demo recording for MCP apps, and publication countries, release notes, and translations. These belong to submission and publication workflows and are not needed just to display a custom icon in Reliquary's marketplace. [OpenAI Docs: review and publication fields](https://developers.openai.com/plugins/deploy/submission)
|
||||
|
||||
## Do other harnesses read these icon fields?
|
||||
|
||||
The **asset file is reusable**, but icon metadata is currently **client-specific**:
|
||||
|
||||
| Consumer | Field to use | What is documented |
|
||||
| --- | --- | --- |
|
||||
| Codex / OpenAI plugin listing | `.codex-plugin/plugin.json` → `interface.logo`; `interface.composerIcon` for the composer | OpenAI reads these presentation fields. In a future portable root `plugin.json`, put them under `extensions.com.openai.interface` instead. |
|
||||
| Anthropic plugin directory | `.claude-plugin/plugin.json` → top-level `icon`, pointing to an image inside the plugin such as `./assets/logo.png` | Anthropic says its directory reads the field when a plugin is submitted. Claude Code ignores the field at plugin load time. |
|
||||
| Portable Agent Plugins 1.0 specification | No standard icon or logo field | Its root `plugin.json` schema is closed. Client-specific presentation belongs under `extensions`; other clients ignore extensions they do not implement. |
|
||||
|
||||
Thus adding OpenAI's `interface.logo` alone does **not** make every harness show that logo. Spire now references one image file at `plugins/spire/assets/spire_logo512.png` from Codex's `interface.logo` and Claude's top-level `icon` in its separate manifest. Even then, there is no documented guarantee that Claude Code's own marketplace UI will render that `icon` field: its docs explicitly say Claude Code ignores it at load time. The repo and plugin READMEs also reference the emoji image so the branding appears in ordinary Markdown views. [Claude Code plugin manifest reference](https://code.claude.com/docs/en/plugins-reference), [Agent Plugins manifest](https://agent-plugins.org/plugin-authors/manifest), [Agent Plugins client extensions](https://agent-plugins.org/plugin-authors/client-extensions)
|
||||
|
||||
## Suggested workflow for Reliquary
|
||||
|
||||
1. Put the existing Spire and Tome artwork in each plugin's own `assets/` directory, using a supported square image format.
|
||||
2. Add `interface.logo` and `interface.composerIcon` to each `.codex-plugin/plugin.json`; add the other `interface` fields needed for readable listing copy. Add `skills: "./skills/"` where appropriate.
|
||||
3. If Anthropic directory listing is a target, reference each same image from the corresponding `.claude-plugin/plugin.json` via its separate top-level `icon` field. If the repository README should show the logo in every harness, add a normal relative Markdown image there as well.
|
||||
4. Validate the JSON and asset paths locally, then commit and push the repository changes to `git.g4b.org`.
|
||||
5. Refresh the registered Git marketplace (`codex plugin marketplace upgrade reliquary` is the documented CLI form), then refresh or reinstall the plugin in the desktop Plugins view and inspect the icon. Installed plugins are copied into a cache; changing the source repository alone need not update an already installed copy immediately. Use `codex plugin marketplace list` to confirm which marketplace source Codex is tracking. [OpenAI Docs: marketplace CLI and installed copies](https://developers.openai.com/plugins/build/plugins)
|
||||
|
||||
Spire's manifest and README changes were implemented after the initial report; Tome remains pending artwork.
|
||||
Reference in New Issue
Block a user