@intentic/extension-manifest 1.312.0 → 1.314.0

package/intentic-extension.schema.json

@@ -54,12 +54,20 @@
         "entry": {
             "description": "Repo-relative path of your prebuilt single-file ESM bundle, built with `vue` and `@intentic/extension-api` as externals. Absent ⇒ an extension with no UI.",
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "power": {
+                "key": "entry",
+                "sentence": "runs a UI bundle in your browser"
+            }
         },
         "server": {
             "description": "Repo-relative path of your prebuilt single-file node ESM server bundle, exporting `activateServer`. Served under your own route namespace, which the daemon proxies. Nothing is provided at runtime but node builtins, so bundle everything else in. Absent ⇒ no backend.",
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "power": {
+                "key": "server",
+                "sentence": "runs a backend bundle inside the daemon's extension host"
+            }
         },
         "permissions": {
             "description": "How far this extension may reach into the daemon, as \"<METHOD> <path-glob>\" entries where `*` matches one path segment: e.g. \"GET /panels\", \"POST /panels/*/start\". The install dialog shows these, the host refuses anything undeclared, and the usage ledger records which were actually earned.",
@@ -69,14 +77,22 @@
                     "description": "Daemon routes your UI half may call. Your own backend namespace needs no entry: its backend is your own code.",
                     "type": "array",
                     "items": {
-                        "type": "string"
+                        "type": "string",
+                        "power": {
+                            "key": "sandbox:${value}",
+                            "sentence": "its UI calls the sandbox route ${value}"
+                        }
                     }
                 },
                 "daemon": {
                     "description": "Daemon routes your SERVER half may call. Separate from `sandbox` because the two halves run as different principals: the UI as the owner's session, the backend as a minted per-extension token, so a grant to one must never quietly widen the other.",
                     "type": "array",
                     "items": {
-                        "type": "string"
+                        "type": "string",
+                        "power": {
+                            "key": "daemon:${value}",
+                            "sentence": "its backend calls the daemon route ${value}"
+                        }
                     }
                 }
             },
@@ -110,6 +126,10 @@
                             },
                             "badge": {
                                 "description": "Allow this view to say something on its tile: a count, a glyph, or that work is running there. Declared because a badge interrupts from every other screen in the app; leave it out and any badge the extension registers is dropped.",
+                                "power": {
+                                    "key": "view-badge:${id}",
+                                    "sentence": "may badge the \"${label}\" tile from any screen"
+                                },
                                 "type": "boolean"
                             }
                         },
@@ -118,6 +138,10 @@
                             "label",
                             "surface"
                         ],
+                        "power": {
+                            "key": "view:${id}",
+                            "sentence": "a ${surface} view \"${label}\""
+                        },
                         "additionalProperties": false
                     },
                     "description": "Sidebar elements this extension may register at runtime. Each entry reserves an id and a surface; the extension supplies the component with api.views.register, and the host refuses any registration this list does not cover."
@@ -146,6 +170,10 @@
                             "path",
                             "invalidates"
                         ],
+                        "power": {
+                            "key": "files:${path}",
+                            "sentence": "is told when ${path} changes"
+                        },
                         "additionalProperties": false
                     },
                     "description": "Which workspace files back your views, so the daemon's file watcher can tell the browser they went stale instead of you polling for it. The agent edits the workspace out of band from every HTTP route, and this push is the only thing that can notice."
@@ -192,6 +220,10 @@
                             "extensions",
                             "fetch"
                         ],
+                        "power": {
+                            "key": "viewer:${id}",
+                            "sentence": "${edit?opens and edits:opens}${compare? and compares:} .${extensions|, .} files (${fetch})"
+                        },
                         "additionalProperties": false
                     },
                     "description": "File formats this extension can render. The host resolves an opened file to your viewer by its extension, fetches the content, and renders your component with it: you keep none of the fetch lifecycle and none of the daemon credentials."
@@ -215,6 +247,10 @@
                             "id",
                             "label"
                         ],
+                        "power": {
+                            "key": "document:${id}",
+                            "sentence": "marks workspace directories (\"${label}\")"
+                        },
                         "additionalProperties": false
                     },
                     "description": "Per-directory documents this extension can offer. Your provider marks the rows in the Workspace tree it has something to say about, and the host opens your component as a tab."
@@ -244,6 +280,10 @@
                             },
                             "keybinding": {
                                 "description": "A global keyboard shortcut, e.g. \"Mod+Shift+K\" — `Mod` is ⌘ on Apple and Ctrl elsewhere. Declared here because a global shortcut is consequential: the owner approves it at install, and the host binds only what was approved.",
+                                "power": {
+                                    "key": "keybinding:${command}",
+                                    "sentence": "the global shortcut ${keybinding} (\"${title}\")"
+                                },
                                 "type": "string",
                                 "pattern": "^\\S+$"
                             },
@@ -256,6 +296,10 @@
                             "command",
                             "title"
                         ],
+                        "power": {
+                            "key": "command:${command}",
+                            "sentence": "a palette command \"${title}\""
+                        },
                         "additionalProperties": false
                     },
                     "description": "Commands this extension may register handlers for, surfaced in the command palette. Title, icon and shortcut all come from here rather than from the registration call, because this is what the owner approved at install."
@@ -307,6 +351,10 @@
                             },
                             "env": {
                                 "description": "Inject the stored value into the agent's shell environment under this name, every turn. How a credential you hold reaches the agent's command-line tools.",
+                                "power": {
+                                    "key": "setting-env:${key}",
+                                    "sentence": "puts the \"${key}\" setting into the agent's environment as ${env}"
+                                },
                                 "type": "string",
                                 "pattern": "^[A-Z][A-Z0-9_]*$"
                             }
@@ -355,6 +403,11 @@
                             "name",
                             "command"
                         ],
+                        "effect": "process",
+                        "power": {
+                            "key": "process:${name}",
+                            "sentence": "a background process \"${name}\"${autoStart? (starts on boot):}"
+                        },
                         "additionalProperties": false
                     },
                     "description": "Long-lived background processes the daemon runs for this extension: a gateway holding a connection the daemon must not, a dev server. Managed the same way panel dev servers are, and startable and stoppable from the Extensions tab."
@@ -367,7 +420,11 @@
                             "type": "string"
                         }
                     },
-                    "description": "Declare that this checkout is also a Claude Code plugin, so the agent picks up its skills, agents, hooks, commands and MCP servers each turn. The daemon hands the directory to the plugin loader and never parses what is in it.",
+                    "power": {
+                        "key": "agent",
+                        "sentence": "contributes skills, agents and hooks to the agent's turns"
+                    },
+                    "description": "Declare that this checkout is also a Claude Code plugin, so Claude Code turns pick up its skills, agents, hooks and commands. Only Claude Code reads it: give the agent tools with `contributes.tools`, which every runtime gets, and put a skill every runtime should read in a capability card's `skill`. MCP servers in the plugin's `.mcp.json` are deprecated, reach Claude Code alone, and are warned about at load.",
                     "additionalProperties": false
                 },
                 "environment": {
@@ -382,6 +439,11 @@
                     "required": [
                         "fragment"
                     ],
+                    "effect": "image",
+                    "power": {
+                        "key": "environment",
+                        "sentence": "bakes an environment fragment into the sandbox image"
+                    },
                     "description": "A Dockerfile fragment baked into the sandbox image so your tools are actually installed at runtime: a whisper binary, a psql client. The owner approves the composed overlay and rebuilds out of band, so this does not take effect immediately.",
                     "additionalProperties": false
                 },
@@ -573,11 +635,13 @@
                                     },
                                     "fragment": {
                                         "description": "A Dockerfile fragment holding the client binary this tool needs (psql, mysql, whisper).",
+                                        "effect": "image",
                                         "type": "string",
                                         "minLength": 1
                                     },
                                     "pack": {
                                         "description": "A sandbox feature pack name (whisper, llamacpp, browser, …) supplying this tool. Preferred over `fragment`: an image that already bakes the pack needs no rebuild, and there is no copy to drift.",
+                                        "effect": "image",
                                         "type": "string",
                                         "minLength": 1
                                     },
@@ -624,9 +688,15 @@
                                         "additionalProperties": false
                                     },
                                     "mcp": {
-                                        "description": "A path in this extension's backend (`server`) answering MCP over Streamable HTTP. Every turn granted a card of this kind gets it as a server named by the card's id; each request arrives at `<path>/<card id>`, so the backend reads that card's config through the daemon rather than the turn's environment.",
+                                        "description": "Deprecated: declare `contributes.tools` with `perCard` naming this card instead, and serve the tools with `api.tools.serve`. A path in this extension's backend (`server`) answering MCP over Streamable HTTP; every turn granted a card of this kind gets it as a server named by the card's id, each request arriving at `<path>/<card id>`.",
+                                        "effect": "mcp",
+                                        "mintsServer": true,
+                                        "power": {
+                                            "key": "capability-tools:${id}",
+                                            "sentence": "serves MCP tools to the agent for each \"${catalog.name}\" card"
+                                        },
                                         "type": "string",
-                                        "pattern": "^[a-z0-9][a-z0-9/-]*$"
+                                        "pattern": "^[a-z0-9][a-z0-9-]*(?:\\/[a-z0-9][a-z0-9-]*)*$"
                                     }
                                 },
                                 "required": [
@@ -1007,6 +1077,7 @@
                                     "kind",
                                     "skill"
                                 ],
+                                "mintsServer": true,
                                 "additionalProperties": false
                             },
                             {
@@ -1192,6 +1263,7 @@
                                     "kind",
                                     "skill"
                                 ],
+                                "mintsServer": true,
                                 "additionalProperties": false
                             },
                             {
@@ -1368,7 +1440,11 @@
                                 ],
                                 "additionalProperties": false
                             }
-                        ]
+                        ],
+                        "power": {
+                            "key": "capability:${id}",
+                            "sentence": "a ${kind} capability card \"${catalog.name}\""
+                        }
                     },
                     "description": "Capability cards this pack adds to the \"+\" grid: a connected CLI tool, a site the agent acts on as the owner through the shared browser, an operating system pack, a browser family the owner connects their own copy of, or a preset over a core kind. The card and its form are data here; the machinery that acts on them is core, which is why a card may only name one of these five kinds."
                 },
@@ -1531,6 +1607,10 @@
                         "events",
                         "automation"
                     ],
+                    "power": {
+                        "key": "listener:${provider}",
+                        "sentence": "a realtime listener provider \"${provider}\""
+                    },
                     "description": "A realtime event source this extension supplies, so automations can trigger on it. One declaration feeds both halves: the daemon accepts these event types and serves this provider's control surface, and the automation editor derives its source picker, filters and starter prompt from it, so a newly installed listener is configurable without a matching app release.",
                     "additionalProperties": false
                 },
@@ -1656,7 +1736,39 @@
                 "bin": {
                     "type": "string",
                     "minLength": 1,
+                    "power": {
+                        "key": "bin",
+                        "sentence": "puts its shipped tools on the agent's PATH"
+                    },
                     "description": "A checkout-relative directory of executables the daemon puts on the agent's PATH every turn, how you ship the agent a command-line tool. The files are the approved code themselves: they ride the pinned checkout, and the daemon only adds the directory to PATH."
+                },
+                "tools": {
+                    "type": "object",
+                    "properties": {
+                        "perCard": {
+                            "description": "The id of one of this extension's `cli` capability cards. Every turn granted a card of that kind gets one server named by the card's id, handed that card's settings (secrets included) with each call. Absent ⇒ one server for the extension, named by its `name`, in every turn while the extension is enabled.",
+                            "type": "string",
+                            "pattern": "^[a-z0-9][a-z0-9-]*$"
+                        },
+                        "process": {
+                            "description": "A process from `contributes.processes`, declared with `port: \"auto\"`, that answers MCP over Streamable HTTP at `path` on its port. Absent ⇒ your `server` bundle serves the tools.",
+                            "type": "string",
+                            "pattern": "^[a-z0-9][a-z0-9-]*$"
+                        },
+                        "path": {
+                            "description": "Where the MCP endpoint answers, without a leading or trailing slash: on the process's port, or in your backend's own namespace when your `server` bundle speaks MCP itself. Absent with no `process` ⇒ the host serves what `api.tools.serve` returns, which is what you want: the host owns the transport, the deadlines and the card lookup. With `perCard`, a request arrives at `<path>/<card id>`.",
+                            "type": "string",
+                            "pattern": "^[a-z0-9][a-z0-9-]*(?:\\/[a-z0-9][a-z0-9-]*)*$"
+                        }
+                    },
+                    "effect": "mcp",
+                    "mintsServer": true,
+                    "power": {
+                        "key": "tools${perCard?-${perCard}:}",
+                        "sentence": "gives the agent MCP tools${perCard?, one server for each \"${perCard}\" card:}"
+                    },
+                    "description": "Tools for the agent, as an MCP server the daemon mounts into every turn and every runtime (Claude Code, Codex, Cursor, ACP agents). Serve them from your `server` bundle with `api.tools.serve((card) => [...])`, or from a declared process's port. Replaces an agent plugin's `.mcp.json`, which only Claude Code read.",
+                    "additionalProperties": false
                 }
             },
             "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-manifest",
-  "version": "1.312.0",
+  "version": "1.314.0",
   "description": "What an intentic extension DECLARES, the intentic-extension.json schema and the sandbox-route allowlist rule",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     }
   },
   "dependencies": {
-    "@intentic/base": "1.312.0",
+    "@intentic/base": "1.314.0",
     "tslib": "2.8.1",
     "zod": "4.6.5"
   },

package/src/index.ts

@@ -2,6 +2,8 @@ export * from "./bundle.js";
 export * from "./contribution-point.js";
 export * from "./json-schema.js";
 export * from "./manifest.js";
+export * from "./meaning.js";
 export * from "./permissions.js";
 export * from "./points/index.js";
 export * from "./powers-diff.js";
+export * from "./tool-servers.js";

package/src/manifest.ts

@@ -6,7 +6,7 @@ import { contributesSchema } from "./points/index.js";
 // dialog renders, and the host refuses any runtime registration whose id it didn't declare here. This file is the
 // envelope only; contributions are assembled from points/.
 
-export const ExtensionManifestSchema = z.object({
+const ManifestShape = z.object({
     // Declared so it survives the parse instead of being silently stripped; nothing at runtime reads it.
     $schema: z.string().optional().describe("The authoring schema, for editor completion and validation. Nothing at runtime reads it."),
     publisher: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
@@ -32,6 +32,7 @@ export const ExtensionManifestSchema = z.object({
         .string()
         .min(1)
         .refine((value) => !value.split("/").includes(".."), { message: "entry must stay inside the checkout" })
+        .meta({ power: { key: "entry", sentence: "runs a UI bundle in your browser" } })
         .optional()
         .describe(
             "Repo-relative path of your prebuilt single-file ESM bundle, built with `vue` and `@intentic/extension-api` as externals. Absent ⇒ an extension with no UI.",
@@ -41,6 +42,7 @@ export const ExtensionManifestSchema = z.object({
         .string()
         .min(1)
         .refine((value) => !value.split("/").includes(".."), { message: "server must stay inside the checkout" })
+        .meta({ power: { key: "server", sentence: "runs a backend bundle inside the daemon's extension host" } })
         .optional()
         .describe(
             "Repo-relative path of your prebuilt single-file node ESM server bundle, exporting `activateServer`. Served under your own route namespace, which the daemon proxies. Nothing is provided at runtime but node builtins, so bundle everything else in. Absent ⇒ no backend.",
@@ -52,11 +54,11 @@ export const ExtensionManifestSchema = z.object({
     permissions: z
         .object({
             sandbox: z
-                .array(z.string())
+                .array(z.string().meta({ power: { key: "sandbox:${value}", sentence: "its UI calls the sandbox route ${value}" } }))
                 .optional()
                 .describe("Daemon routes your UI half may call. Your own backend namespace needs no entry: its backend is your own code."),
             daemon: z
-                .array(z.string())
+                .array(z.string().meta({ power: { key: "daemon:${value}", sentence: "its backend calls the daemon route ${value}" } }))
                 .optional()
                 .describe(
                     "Daemon routes your SERVER half may call. Separate from `sandbox` because the two halves run as different principals: the UI as the owner's session, the backend as a minted per-extension token, so a grant to one must never quietly widen the other.",
@@ -68,6 +70,41 @@ export const ExtensionManifestSchema = z.object({
         ),
     contributes: contributesSchema.optional(),
 });
+
+// What each field means taken together, which no one field's schema can say: tools need something to serve them.
+const servedTools = (manifest: z.infer<typeof ManifestShape>, ctx: z.RefinementCtx): void => {
+    const contributes = manifest.contributes;
+    const tools = contributes?.tools;
+    const cards = contributes?.capabilities ?? [];
+    for (const card of cards) {
+        if (card.kind === "cli" && card.mcp !== undefined && manifest.server === undefined) {
+            ctx.addIssue({ code: "custom", path: ["contributes", "capabilities"], message: `card "${card.id}" declares \`mcp\`, which only a \`server\` bundle can answer` });
+        }
+    }
+    if (tools === undefined) {
+        return;
+    }
+    if (tools.process !== undefined) {
+        const process = contributes?.processes?.find((entry) => entry.name === tools.process);
+        if (process?.port !== "auto") {
+            ctx.addIssue({
+                code: "custom",
+                path: ["contributes", "tools", "process"],
+                message: `tools.process must name a process in contributes.processes declared with port: "auto"`,
+            });
+        }
+        if (tools.path === undefined) {
+            ctx.addIssue({ code: "custom", path: ["contributes", "tools", "path"], message: "tools served by a process need the path its MCP endpoint answers at" });
+        }
+    } else if (manifest.server === undefined) {
+        ctx.addIssue({ code: "custom", path: ["contributes", "tools"], message: "tools need a `server` bundle to serve them, or a `process` that does" });
+    }
+    if (tools.perCard !== undefined && !cards.some((card) => card.kind === "cli" && card.id === tools.perCard)) {
+        ctx.addIssue({ code: "custom", path: ["contributes", "tools", "perCard"], message: `tools.perCard must name one of this extension's cli cards` });
+    }
+};
+
+export const ExtensionManifestSchema = ManifestShape.superRefine(servedTools);
 export type ExtensionManifest = z.infer<typeof ExtensionManifestSchema>;
 
 // The extension's identity everywhere (capability entries, /ext routes, settings namespaces); derived, never declared,

package/src/meaning.ts

@@ -0,0 +1,189 @@
+import type { z } from "zod";
+
+// What a manifest field MEANS to the host, declared on the field itself with `.meta()`, so the schema is the one place
+// that says it: the powers an update re-asks for (powers-diff.ts), what adding a card does to the sandbox (the capability
+// catalog's effects) and which capability kinds register an `mcp__<id>__` server (the contract's reserved names) are all
+// read from here, never re-listed beside the schema.
+
+// A template is plain text with `${path}` holes filled from the entry the field belongs to: `${id}`, `${catalog.name}`,
+// and `${value}` for a scalar in a list. `${path|sep}` joins a list with `sep` (", " by default), `${path?yes:no}` picks
+// by whether the value is set and not false.
+export interface PowerMeaning {
+    // The stable key an owner's approval is pinned to: an update re-asks when a key appears.
+    readonly key: string;
+    // The plain sentence shown for it.
+    readonly sentence: string;
+}
+
+// The capability-catalog effect a field adds when it is present on a card (`@intentic/capability-catalog`, effects.ts).
+export type EffectMeaning = "mcp" | "image" | "process";
+
+export interface FieldMeaning {
+    // Present (and not `false`) grants this power.
+    readonly power?: PowerMeaning;
+    readonly effect?: EffectMeaning;
+    // A card of this kind, or with this field set, registers an `mcp__<card id>__` server for the turn.
+    readonly mintsServer?: boolean;
+}
+
+// The meaning a schema carries, gathered through its wrappers (optional, default, pipe): `.meta()` may sit on any of
+// them, and a `.describe()` clone inherits its parent's.
+const readMeta = (schema: z.ZodType): FieldMeaning => {
+    const { power, effect, mintsServer } = (schema.meta() ?? {}) as FieldMeaning;
+    return { ...(power === undefined ? {} : { power }), ...(effect === undefined ? {} : { effect }), ...(mintsServer === undefined ? {} : { mintsServer }) };
+};
+
+const WRAPPERS = new Set(["optional", "nullable", "default", "prefault", "readonly", "nonoptional", "catch"]);
+
+interface Unwrapped {
+    readonly schema: z.ZodType;
+    readonly meaning: FieldMeaning;
+}
+
+// The schema under its wrappers, with every meaning met on the way down merged (the outermost wins a clash).
+export const unwrapMeaning = (schema: z.ZodType): Unwrapped => {
+    let current = schema;
+    // Outermost first, so the merge below lets it win.
+    const met: FieldMeaning[] = [];
+    for (;;) {
+        met.unshift(readMeta(current));
+        const def = current._zod.def as unknown as { type: string; innerType?: z.ZodType; in?: z.ZodType };
+        if (WRAPPERS.has(def.type) && def.innerType !== undefined) {
+            current = def.innerType;
+        } else if (def.type === "pipe" && def.in !== undefined) {
+            current = def.in;
+        } else {
+            return { schema: current, meaning: Object.assign({}, ...met) as FieldMeaning };
+        }
+    }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const lookup = (context: Record<string, unknown>, path: string): unknown =>
+    path.split(".").reduce<unknown>((at, part) => (isRecord(at) ? at[part] : undefined), context);
+
+const present = (value: unknown): boolean => value !== undefined && value !== null && value !== false && value !== "";
+
+// The template's holes, outermost only, so a branch of `${path?yes:no}` may hold holes of its own.
+const holesOf = (template: string): { readonly start: number; readonly end: number; readonly body: string }[] => {
+    const holes: { start: number; end: number; body: string }[] = [];
+    for (let at = template.indexOf("${"); at !== -1; at = template.indexOf("${", at)) {
+        let depth = 0;
+        let close = -1;
+        for (let i = at + 1; i < template.length; i++) {
+            if (template[i] === "{") {
+                depth++;
+            } else if (template[i] === "}" && --depth === 0) {
+                close = i;
+                break;
+            }
+        }
+        if (close === -1) {
+            break;
+        }
+        holes.push({ start: at, end: close + 1, body: template.slice(at + 2, close) });
+        at = close + 1;
+    }
+    return holes;
+};
+
+// Fills a template's holes from `context`; see PowerMeaning for the three forms.
+export const fillTemplate = (template: string, context: Record<string, unknown>): string => {
+    let filled = "";
+    let from = 0;
+    for (const hole of holesOf(template)) {
+        filled += template.slice(from, hole.start);
+        from = hole.end;
+        const choice = /^([\w.]+)\?([\s\S]*)$/u.exec(hole.body);
+        if (choice !== null) {
+            // The branch separator is the first `:` outside a nested hole.
+            const branches = choice[2] ?? "";
+            let depth = 0;
+            let split = -1;
+            for (let i = 0; i < branches.length; i++) {
+                const char = branches[i];
+                depth += char === "{" ? 1 : char === "}" ? -1 : 0;
+                if (char === ":" && depth === 0) {
+                    split = i;
+                    break;
+                }
+            }
+            const [yes, no] = split === -1 ? [branches, ""] : [branches.slice(0, split), branches.slice(split + 1)];
+            filled += fillTemplate(present(lookup(context, choice[1] ?? "")) ? yes : no, context);
+            continue;
+        }
+        const [path = "", separator = ", "] = hole.body.split("|");
+        const value = lookup(context, path);
+        filled += Array.isArray(value) ? value.map(String).join(separator) : value === undefined || value === null ? "" : String(value);
+    }
+    return filled + template.slice(from);
+};
+
+// Which member of a union a value is: the discriminated union's own key when it has one, else the first that parses.
+const optionFor = (options: readonly z.ZodType[], value: unknown, discriminator: string | undefined): z.ZodType | undefined => {
+    if (discriminator !== undefined && isRecord(value)) {
+        for (const option of options) {
+            const shape = (unwrapMeaning(option).schema as unknown as { shape?: Record<string, z.ZodType> }).shape;
+            const literal = shape?.[discriminator]?._zod.def as { values?: readonly unknown[] } | undefined;
+            if (literal?.values?.includes(value[discriminator]) === true) {
+                return option;
+            }
+        }
+    }
+    return options.find((option) => option.safeParse(value).success);
+};
+
+// Walks a value alongside its schema, calling `visit` for each node carrying a meaning, with the value there and the
+// entry it belongs to (the object itself for an object, the enclosing one for a field, `{ value }` over it for a scalar
+// in a list).
+export const walkMeaning = (
+    schema: z.ZodType,
+    value: unknown,
+    visit: (meaning: FieldMeaning, context: Record<string, unknown>) => void,
+    parent: Record<string, unknown> = {},
+): void => {
+    if (!present(value)) {
+        return;
+    }
+    const { schema: inner, meaning } = unwrapMeaning(schema);
+    const context = isRecord(value) ? value : { ...parent, value };
+    if (Object.keys(meaning).length > 0) {
+        visit(meaning, context);
+    }
+    const def = inner._zod.def as unknown as {
+        type: string;
+        shape?: Record<string, z.ZodType>;
+        element?: z.ZodType;
+        options?: readonly z.ZodType[];
+        discriminator?: string;
+    };
+    if (def.type === "object" && def.shape !== undefined && isRecord(value)) {
+        for (const [key, field] of Object.entries(def.shape)) {
+            walkMeaning(field, value[key], visit, value);
+        }
+    } else if (def.type === "array" && def.element !== undefined && Array.isArray(value)) {
+        for (const element of value) {
+            walkMeaning(def.element, element, visit, parent);
+        }
+    } else if (def.type === "union" && def.options !== undefined) {
+        const option = optionFor(def.options, value, def.discriminator);
+        if (option !== undefined) {
+            walkMeaning(option, value, visit, parent);
+        }
+    }
+};
+
+// Every field of an object schema (or a union of them) that carries a meaning, by key, without a value: what a schema
+// declares, as opposed to what one manifest uses.
+export const fieldMeanings = (schema: z.ZodType): Map<string, FieldMeaning> => {
+    const meanings = new Map<string, FieldMeaning>();
+    const shape = (unwrapMeaning(schema).schema as unknown as { shape?: Record<string, z.ZodType> }).shape ?? {};
+    for (const [key, field] of Object.entries(shape)) {
+        const { meaning } = unwrapMeaning(field);
+        if (Object.keys(meaning).length > 0) {
+            meanings.set(key, meaning);
+        }
+    }
+    return meanings;
+};

package/src/points/agent.ts

@@ -3,15 +3,17 @@ import type { ContributionPoint } from "../contribution-point.js";
 
 // "This checkout is ALSO a Claude Code plugin": the daemon hands the directory to the Agent SDK's plugin
 // loader, which reads skills/agents/hooks/commands/.mcp.json each turn, the daemon never parses plugin
-// internals.
+// internals. Only Claude Code turns read it, so tools belong in `contributes.tools` and a skill every runtime should
+// read in a capability card's `skill`; a `.mcp.json` here is deprecated and warned about at load.
 export const AgentContributionSchema = z.object({
     path: z.string().optional().describe("Relative to the extension checkout. Absent ⇒ the checkout root."),
-});
+})
+    .meta({ power: { key: "agent", sentence: "contributes skills, agents and hooks to the agent's turns" } });
 export type AgentContribution = z.infer<typeof AgentContributionSchema>;
 
 export const agentPoint = {
     name: "agent",
     description:
-        "Declare that this checkout is also a Claude Code plugin, so the agent picks up its skills, agents, hooks, commands and MCP servers each turn. The daemon hands the directory to the plugin loader and never parses what is in it.",
+        "Declare that this checkout is also a Claude Code plugin, so Claude Code turns pick up its skills, agents, hooks and commands. Only Claude Code reads it: give the agent tools with `contributes.tools`, which every runtime gets, and put a skill every runtime should read in a capability card's `skill`. MCP servers in the plugin's `.mcp.json` are deprecated, reach Claude Code alone, and are warned about at load.",
     schema: AgentContributionSchema,
 } as const satisfies ContributionPoint;

package/src/points/bin.ts

@@ -11,5 +11,6 @@ export const binPoint = {
     schema: z
         .string()
         .min(1)
-        .refine((value) => !value.split("/").includes(".."), { message: "bin must stay inside the checkout" }),
+        .refine((value) => !value.split("/").includes(".."), { message: "bin must stay inside the checkout" })
+        .meta({ power: { key: "bin", sentence: "puts its shipped tools on the agent's PATH" } }),
 } as const satisfies ContributionPoint;