Add portable display metadata (displayName and icon) to the manifest

[digitarald]

Summary

Adds a modest, portable display-metadata pair to the closed plugin manifest — displayName and icon — and consolidates the two prior open PRs on this topic into a single self-contained change.

This supersedes and folds in the worthwhile parts of:

• Add optional displayName field to plugin manifest #17 — Add optional displayName field (closes Add optional displayName field to the plugin manifest #16)
• Add optional icon field to plugin manifest #19 — Add optional icon field (closes Add optional icon #18)

Rather than leaving three competing PRs, this one change lands both fields consistently across the spec text, the official JSON schema, examples, the conformance checklist, and Design Decisions. #17 and #19 can be closed in favor of this PR.

What's added

displayName (§5.7)

Optional, unconstrained, human-readable label for host UIs. Hosts MAY present it instead of the constrained machine identifier name (§5.5); when it is absent or empty, hosts fall back to name. name is re-described as the plugin identifier now that displayName carries the label role (adopted from #17).

icon (§5.8)

Optional plugin-relative path (§4.1) to an image representing the plugin.

Deliberately narrower than #19: remote http:/https: icon references are excluded. Assets ship inside the package and are covered by the existing §4.1 containment rules, which removes load-time fetching, SSRF, and privacy concerns entirely and answers the open questions raised in #18:

• Failure behavior: non-fatal. A non-string icon is a fatal type violation (like other metadata); a string icon with an invalid or out-of-root path is advisory — ignored, never affecting component discovery or execution.
• Remote fetching: not defined / prohibited at load time, consistent with the §5.2 schema-retrieval ban.
• Formats / active content: host-defined, but a host that renders the icon MUST treat it as untrusted image data, MUST NOT execute active content (e.g. script in an SVG), and MUST NOT trigger any network request — including subresource resolution — while rendering.

Scope: chosen vs. rejected

Grounded in cross-host practice (Claude marketplace is minimal; Cursor exposes displayName/logo/category/tags; OpenAI carries rich client-specific interface metadata), the portable core is limited to the two fields that mean the same thing across hosts and packages.

Explicitly rejected / left to client extensions (§8): a category or other taxonomy field (overlaps keywords, drifts toward marketplace/ranking semantics), remote icon URLs, screenshots, colors, starter prompts, legal/policy URLs, and marketplace ranking signals. An exploratory category field was considered and dropped to keep the addition narrow.

Compatibility

Both fields are optional and required is unchanged, so existing conformant plugins stay valid and existing hosts treat the fields as known-optional (or, on older hosts, as report-and-ignore unknown fields per §5.2). No backwards-incompatible change.

Consistency / tests

The repository has no build or test harness (spec = README.md + JSON schemas). Validation performed:

• schemas/1.0.0/plugin.schema.json parses as valid JSON.
• All four plugin.json examples in the README validate against the updated schema via jsonschema (including the full example with displayName + icon).
• Section numbering (§5.6→§5.7→§5.8→§6), field lists (§5.2 / §5.4 / schema), anchors, and the fatal-vs-advisory rules (§5.2, §5.4, §5.8, §11.3) were cross-checked for consistency.

Adversarial review

Two independent read-only reviews of the final diff (Claude Opus and GPT-5.6):

• Round 1 — both flagged that icon was described as advisory in §5.8 but made fatal by the general rules in §5.2/§5.4/§11.3, and that icon rendering security (active content / embedded subresource fetches) was only a SHOULD. Both addressed: non-string icon is now explicitly fatal while a bad path is explicitly advisory across §5.2/§5.4/§5.8/§11.3, and the render-time security requirements were raised to MUST NOT.
• Round 2 (re-review of the fixes) — both returned SHIP with no new issues.

Changed files

• README.md
• schemas/1.0.0/plugin.schema.json

---

This is a community contribution and does not imply endorsement or consensus from any host or vendor.

Supersedes #17. Supersedes #19. Refs #16, #18.