Remove deprecated inline plugin definitions in plugins.json (target: ~2026-09)

[tadasant]

Background

As of v0.13.0 (PR #155), a plugin entry can externalize its body into a <path>/.plugin/plugin.json manifest, keeping plugins.json a lightweight registry of description + path (+ default_in_roots). See docs/plugins.md → Externalizing the Body.

The prior way — declaring a plugin's body (skills, mcp_servers, hooks, plugins, version, author, homepage, repository, license, logo, keywords, title) inline on a plugins.json entry with no path — is deprecated as of v0.13.0. resolveArtifacts now emits a deprecation warning whenever an inline-only plugin is resolved.

Task (do this in ~3 months, targeting roughly 2026-09)

Remove support for inline plugin bodies:

1. Resolver (packages/core/src/config.ts) — in hydratePluginManifests, turn the inline-body deprecation warning into a hard error (or drop the inline-merge path entirely). A plugin entry must reference a .plugin/plugin.json manifest via path; inline body fields without a path are rejected. Inline fields layered on top of a path (the sanctioned override case) remain allowed.
2. Schema (schemas/plugins.schema.json) — remove the deprecated inline body properties (skills, mcp_servers, hooks, plugins, version, author, homepage, repository, license, logo, title, keywords) from the Plugin definition, OR constrain the schema so those fields require a sibling path. Keep description, path, default_in_roots.
3. Types (packages/core/src/types.ts) — narrow PluginEntry accordingly if appropriate.
4. Tests — flip the deprecation-warning tests in packages/core/tests/plugin-manifest.test.ts to expect a hard error for inline-only plugins; ensure manifest-backed and override cases still pass.
5. Docs / examples — remove any remaining mention of inline plugin bodies as a supported form; ensure all examples/plugins/ entries use the manifest form.
6. CHANGELOG — note the removal as a breaking change in the version that ships it.

Migration for users

Move each inline plugin's body into <plugin-dir>/.plugin/plugin.json and replace the inline fields in plugins.json with "path": "./<plugin-dir>". Keep description, path, and default_in_roots on the index entry. The warning emitted in the deprecation window names each affected plugin and the fields to move.

Deprecated in v0.13.0 (PR #155).

[tadasant]

🚦 Issue gate

Kind: tech-debt (⚪ normal — not the fast lane, because it is not behaviour-preserving) · Scope: convergent · Facets: subtractive

Verdict: HELD — A2, a permanent exclusion on this surface. Two of ISSUE_WORK_GATE_AIR_FRAMEWORK.md's permanent exclusions land squarely on this task list, and A2 is unconditional and sits above the scope test on purpose — the work being convergent is not in question and is not the point. Step 2 removes published properties from schemas/plugins.schema.json, which is "anything that narrows a schema in schemas/ … removing a property" verbatim; the alternative wording in step 2 (constrain those fields to require a sibling path) is the same narrowing by another route. Step 1 turns hydratePluginManifests' deprecation warning into a hard error, so a catalog that resolves today stops resolving — the exclusion's stated rationale ("narrowing invalidates catalogs that are valid today, including this one, and it does not look like a breaking change in the diff") is exactly this issue. A7 fires independently on the other half: step 6 ships it as a breaking change, and on this surface a version bump merged is a version published.

Live pages: none — not alert-shaped, and nothing in pulsemcp/air is deployed (the surface doc: "nothing here is deployed, so nothing pages"), so anchor 2a has no rule to resolve; anchor 2b — quick_search_sessions for pulsemcp/air issue sessions with show_archived: true — returns no alert-genesis session. Normal dispatch.

Re-entry: a human decides the removal window and the release, since both halves of this are theirs — the schema narrowing and the breaking version. Once that call is made, hand it back: the mechanical work (resolver, types, tests, examples, CHANGELOG) is well specified and would rate as an ordinary proceed on its own.

Rating detail

The rating below is recorded for the ledger; the permanent exclusion decided this, at any rating.

Axis	Rating	Why
Requirement complexity	large	The surface doc's worked example of large: "how a deprecation lands across published packages (#157)". The six steps are clear; what is not is the compatibility reasoning about every catalog in the world that still uses the inline form.
Requirement impact	large	schemas/ defines what a valid catalog is, and hydratePluginManifests is on the resolution path every plugin crosses.
Solution complexity	medium (est.)	Guessing: resolver, schema, types, tests, examples and CHANGELOG — a handful of files with an obvious shape and no open design question.
Implementation risk	large (est.)	Guessing: the diff looks like tidying and the effect is that valid input becomes invalid, with no failure visible until someone else's catalog stops resolving.
Estimated cost	large (est.)	Guessing, and the surface doc names this issue as the large-cost archetype: the work is small and the compatibility reasoning is not.

Note: the three solution-side axes are estimates — there is no diff yet.

Staleness check: live. packages/core/src/config.ts on main still carries hydratePluginManifests (line 174) emitting the inline-body deprecation warning (lines 187–193, "deprecated as of v0.13.0 and will be removed in a future release"), and line 207 names this issue in a comment about the migration window. Nothing has been removed. The ~2026-09 target the title names has arrived, which is why the issue is in front of a gate rather than why it is held — age is not evidence here in either direction.