@plurnk/plurnk-contracts 1.23.0 → 1.25.0

package/SPEC.md

@@ -17,10 +17,10 @@ runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
 | Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
 | Exterior adapter application calls                                             | `ApplicationPort`                                   |
-| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpServerOptions`, `McpConfigurationOverlay` |
+| Workspace MCP configuration                                                    | `McpServerDefinition`, `McpOAuth` |
 | Worker Agent Skills definition                                                 | `SkillDefinition` |
 | Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
-| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
+| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityProvenance`, `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
 | AG-UI discovery, client accounting, and shared conformance specimens           | `AguiDiscovery`, `AguiClientConformance`, `AguiConformanceKit` |
 | JSON Schemas                                                                    | `@plurnk/plurnk-contracts/schema/*.json`            |
 | Generated JSON result rendering                                                 | `renderJsonResult`                                  |
@@ -178,7 +178,7 @@ vocabulary of `proposals`. Capability admission precedes effect
 classification and proposal settlement.
 
 §effort-wire `Effort` is exactly `off | adaptive | low |
-medium | high`. The schema owns this shared wire vocabulary. Providers own the
+medium | high | xhigh | max`. The schema owns this shared wire vocabulary. Providers own the
 supported subset and native projection for a selected route; core owns the
 durable worker value.
 
@@ -964,8 +964,9 @@ Mutation semantics:
 | KILL | Status of deletion or termination                                                 |
 | NOTE / WAIT | Literal memory or wait explanation                              |
 
-§find-result-unit For FIND, authored target shape fixes the paginated result
-unit. An exact target with a matcher pages flat match locations; a glob or
+§find-result-unit For FIND, target selection fixes the paginated result
+unit after scheme address resolution ({§entry-address-resolution}). An exact
+resource target with a matcher pages flat match locations; a glob or
 folder target, and every matcher-less FIND, pages resources. Resolving a glob to
 one resource does not make it exact. The same `<N>`, inclusive `<N,M>`,
 configured markerless first page ({§markerless-first-page}), and explicit-all
@@ -1185,11 +1186,11 @@ operation receives empty-turn recovery, not successful completion ({§empty-turn
 
 | Intent | Nominal status | Meaning |
 |---|---|---|
-| Unanswered messages or unobserved results | 102 | Continue silently |
+| Unobserved messages or results | 102 | Continue silently |
 | No authored response operations or fresh operation/parser failure, without WAIT | 102 | Recover before automatic parking |
 | WAIT | 202 | Park when a live obligation exists; otherwise continue at 102 |
 | Eligible parameterless KILL ({§kill-conclusion}), live work remains, no fresh failure | 202 | Join the held work without delivering its body |
-| Eligible parameterless KILL, results observed, no held work, messages answered or answered by its body | 200 | Deliver the answer and conclude under {§kill-conclusion}; an empty KILL need not repeat a delivered response |
+| Eligible parameterless KILL, messages and results observed, no held work | 200 | Conclude under {§kill-conclusion}; deliver a nonempty body, or finish silently without inventing or repeating a reply |
 | Other admitted program | 102 | Continue regardless of earlier replies or live work |
 | KILL own worker | 499 | Cancel unfinished work in that worker and its descendants |
 | Runtime or infrastructure failure | 5xx | Not a model-authored task status |
@@ -1553,42 +1554,29 @@ model-language syntax or model packet teaching.
 
 ### §mcp-server-definition 13.8 MCP server definitions
 
-`McpServerDefinition` is the transport-neutral normalized definition of one
-workspace MCP server. It is a closed `stdio`/`http` union. The schema
-owns transport-specific fields, enabled/read tool sets, supported HTTP
-authorization choices, and symbolic credential references; it carries no
-workspace identifier, connection state, discovered catalog, or secret value.
-`Validator.assertMcpServerDefinition` is the MCP host's admission boundary
-before persistence or connection work.
-
-§mcp-server-options `McpServerOptions` is the closed client/daemon-shared
-supplement accepted when adding an MCP server by alias and target. It reuses
-only `McpServerDefinition` option fields and cannot repeat identity, target, or
-transport. The target determines the transport; normalization through
-`McpServerDefinition` rejects options belonging to the other transport.
-
-Interactive OAuth always requires a callback URL. Its structurally exclusive
-identity modes are an HTTPS Client ID Metadata Document URL, a pre-registered
-client ID plus symbolic secret, or neither for server-advertised Dynamic Client
-Registration fallback. A definition cannot combine those identity modes.
-
-§mcp-configuration-overlay `McpConfigurationOverlay` is the bounded raw
-configuration projection a client may carry to MCP list and enable actions: its
-string-valued `PLURNK_MCP_*` variables, whole. Which of those names are the
-host's own controls is the host's fact alone — its parser skips every control
-it owns, so a carried timeout or enabled list has no effect and no client or
-contract restates that vocabulary.
-The client does not interpret this map. The MCP host composes it over the
-lower normalized definition through the same parser that admits service
-environment declarations, then validates the resulting
-`McpServerDefinition`. Carrying the overlay does not connect, persist, or
-expand credentials by itself.
+`McpServerDefinition` is the one definition the workspace `mcp` Functionality family
+accepts and persists: one complete connection definition with its alias `name`.
+It is a closed union of the two supported transports, `stdio`
+(`command`, optional `args`, `env`, `cwd`) and `streamable-http` (`url`, optional
+`headers` and `authorization`). Source provenance, workspace scope, connection
+state, catalog and resolved credentials are not definition fields. Adding or
+removing a definition does not install or remove a plugin. Transport and
+authentication fields replace together ({§configuration-definition-resolution}).
+
+§mcp-oauth `McpOAuth` is the client-managed OAuth plurnk holds for one Streamable
+HTTP server, included in that server's `authorization`. Interactive OAuth always requires a callback URL, and
+its structurally exclusive identity modes are an HTTPS Client ID Metadata Document URL,
+a pre-registered client ID with a symbolic secret, or neither for server-advertised
+Dynamic Client Registration. A client-credentials grant names its client ID and
+symbolic secret, optionally binding an issuer. Every secret is one complete `${NAME}`
+reference to the operator environment; `Validator.assertMcpOAuth` validates the shape.
 
 `SkillDefinition` is the one definition the workspace `skills` Functionality
-family accepts and persists: the standard `name`, source `scope`, and optional
-installer `source`. `Validator.assertSkillDefinition` validates the wire shape;
+family accepts and persists: the standard `name`, its `source`, an optional git
+`ref`, and the `commit` the service recorded. Only host-provided trees omit
+`source`; installation scopes are not part of this shape. `Validator.assertSkillDefinition` validates the wire shape;
 the schema's name grammar is exposed as `SKILL_NAME` for loaders and discovery
-({§agent-skills-name}). Core owns installation truth and lifecycle
+({§agent-skills-name}). Core owns source resolution and lifecycle
 ({§skills-functionality}).
 
 `A2aAgentDefinition` is the one definition the Worker `a2a` Functionality
@@ -1609,6 +1597,11 @@ An exterior adapter owns its own protocol validation, identity binding, and
 projection while reusing the same workspace, worker, loop, operation, proposal,
 interaction, and event owners through this port.
 
+`configurationNotices` exposes current launcher-owned configuration diagnostics
+without acquiring a workspace or provider. Adapters use the existing Notice
+projection; model turns combine these with workspace diagnostics according to
+{§configuration-repair-path}.
+
 `runLoop.source` is trusted causal provenance supplied by an adapter, distinct
 from user-authored prompt content. An adapter may expose no public means to set
 it; Core validates and records it through the same prompt admission path.

package/dist/conformance/agui-v1.json

@@ -70,6 +70,7 @@
                                 "model": null,
                                 "loopId": null,
                                 "packetCount": 0,
+                                "preparation": [],
                                 "activity": null
                             }
                         },
@@ -79,6 +80,15 @@
                 {
                     "type": "STATE_DELTA",
                     "delta": [
+                        { "op": "replace", "path": "/plurnk/status/preparation", "value": [
+                            { "family": "mcp", "alias": "search", "phase": "preparing", "since": "2026-09-29T00:00:00.000Z" }
+                        ] }
+                    ]
+                },
+                {
+                    "type": "STATE_DELTA",
+                    "delta": [
+                        { "op": "replace", "path": "/plurnk/status/preparation", "value": [] },
                         { "op": "replace", "path": "/plurnk/status/lifecycle", "value": "running" },
                         { "op": "replace", "path": "/plurnk/status/loopId", "value": 1 },
                         { "op": "replace", "path": "/plurnk/status/packetCount", "value": 1 }
@@ -134,7 +144,7 @@
             ],
             "expect": {
                 "completion": "success",
-                "families": ["log/entry", "loop/packet", "loop/terminated"],
+                "families": ["log/entry", "loop/packet", "loop/terminated", "workspace/preparation"],
                 "status": 200
             }
         },

package/dist/schema/FunctionalityCandidate.json

@@ -19,15 +19,6 @@
             "description": "The exact family definition, conforming to the family's definition schema.",
             "type": "object"
         },
-        "provenance": {
-            "type": "object",
-            "additionalProperties": false,
-            "required": ["kind", "source"],
-            "properties": {
-                "kind": { "type": "string", "minLength": 1 },
-                "source": { "type": "string", "minLength": 1 },
-                "reference": { "type": "string", "minLength": 1 }
-            }
-        }
+        "provenance": { "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json" }
     }
 }

package/dist/schema/FunctionalityDefinitionState.json

@@ -13,10 +13,14 @@
             "enum": ["service", "workspace", "worker"]
         },
         "state": {
-            "description": "disabled: available, model-invisible. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.",
-            "enum": ["disabled", "active", "unavailable", "authorization-required"]
+            "description": "disabled: available, model-invisible. dormant: enabled without a resident publication. active: enabled and prepared. unavailable: enabled but preparation has an exact Problem. authorization-required: enabled and awaiting a protocol continuation.",
+            "enum": ["disabled", "dormant", "active", "unavailable", "authorization-required"]
         },
         "definition": { "type": "object" },
+        "provenance": {
+            "description": "The winning configuration input, when supplied by a source reader. Independent of origin and readiness; absent for locally owned definitions or host-provided resources without a configuration input.",
+            "$ref": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json"
+        },
         "inherited": {
             "description": "The Worker this entry was copied from when this Worker was created (WORK or FORK), preserved across generations until this Worker changes the entry. Absent for an entry this Worker set itself. Worker-scoped families only.",
             "type": "string",

package/dist/schema/FunctionalityDiscoverQuery.json

@@ -9,7 +9,7 @@
         "query": { "type": "string", "minLength": 1 },
         "source": { "type": "string", "minLength": 1 },
         "configuration": {
-            "description": "Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_MCP_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.",
+            "description": "Caller-supplied configuration material the family interprets as candidates (a client's own PLURNK_A2A_* environment, a local directory list). It contributes candidates with client-configuration provenance; it never becomes durable authority.",
             "type": "object"
         }
     }

package/dist/schema/FunctionalityPreparationActivity.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityPreparationActivity.json",
+    "title": "FunctionalityPreparationActivity",
+    "description": "Current workspace capability preparation, not a published outcome. No definitions or credentials.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["family", "alias", "phase", "since"],
+    "properties": {
+        "family": { "type": "string", "minLength": 1 },
+        "alias": { "type": ["string", "null"], "minLength": 1 },
+        "phase": { "enum": ["preparing", "publishing"] },
+        "since": { "type": "string", "format": "date-time" }
+    }
+}

package/dist/schema/FunctionalityProvenance.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/FunctionalityProvenance.json",
+    "title": "FunctionalityProvenance",
+    "description": "The input supplying a definition or discovery candidate, separate from ownership, preparation and authority.",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["kind", "source"],
+    "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "reference": { "type": "string", "minLength": 1 }
+    }
+}

package/dist/schema/McpOAuth.json

@@ -0,0 +1,64 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.xyz/v0/McpOAuth.json",
+    "title": "McpOAuth",
+    "description": "OAuth configuration within one Streamable HTTP MCP server definition. Every secret is a ${NAME} reference to the operator environment.",
+    "oneOf": [
+        {
+            "type": "object",
+            "description": "Interactive OAuth identified by an HTTPS Client ID Metadata Document.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl", "clientMetadataUrl"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "clientMetadataUrl": { "type": "string", "format": "uri", "pattern": "^https://.+/.+" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "Interactive OAuth with a pre-registered client ID and secret.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl", "clientId", "clientSecret"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "clientId": { "type": "string", "minLength": 1 },
+                "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "Interactive OAuth through server-advertised Dynamic Client Registration.",
+            "additionalProperties": false,
+            "required": ["type", "redirectUrl"],
+            "properties": {
+                "type": { "const": "oauth" },
+                "redirectUrl": { "type": "string", "format": "uri" },
+                "scope": { "type": "string", "minLength": 1 }
+            }
+        },
+        {
+            "type": "object",
+            "description": "A noninteractive client-credentials grant; issuer optionally binds the credentials to one authorization server.",
+            "additionalProperties": false,
+            "required": ["type", "clientId", "clientSecret"],
+            "properties": {
+                "type": { "const": "client-credentials" },
+                "clientId": { "type": "string", "minLength": 1 },
+                "clientSecret": { "$ref": "#/$defs/environmentReference" },
+                "scope": { "type": "string", "minLength": 1 },
+                "issuer": { "type": "string", "minLength": 1 }
+            }
+        }
+    ],
+    "$defs": {
+        "environmentReference": {
+            "description": "An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.",
+            "type": "string",
+            "pattern": "^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+        }
+    }
+}

package/dist/schema/McpServerDefinition.json

@@ -2,171 +2,120 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schemas.plurnk.xyz/v0/McpServerDefinition.json",
     "title": "McpServerDefinition",
-    "type": "object",
-    "additionalProperties": false,
-    "required": ["name", "transport"],
-    "properties": {
+    "description": "One complete MCP connection definition. Configuration sources supply it; workspace management persists it without installing a plugin.",
+    "oneOf": [
+        {
+            "$ref": "#/$defs/stdio"
+        },
+        {
+            "$ref": "#/$defs/streamableHttp"
+        }
+    ],
+    "$defs": {
         "name": {
-            "description": "Server alias: the runtime tag whose fence invokes it, and its resource scheme.",
+            "title": "McpServerName",
+            "description": "The server's alias: the runtime tag whose fence invokes it and its resource scheme.",
             "type": "string",
             "pattern": "^[a-z][a-z0-9-]*$"
         },
-        "transport": {
-            "description": "stdio launches a local command; http connects to a remote MCP endpoint.",
-            "enum": ["stdio", "http"]
-        },
-        "command": {
-            "description": "Executable to launch for stdio; arguments belong in args.",
-            "type": "string",
-            "minLength": 1
-        },
-        "args": {
-            "description": "Arguments passed to the stdio executable in order.",
-            "type": "array",
-            "items": { "type": "string" }
-        },
-        "cwd": {
-            "description": "Working directory for the stdio process.",
-            "type": "string",
-            "minLength": 1
-        },
-        "env": {
-            "description": "Environment overrides for the stdio process; values may reference ${ENV_NAME}.",
+        "stdio": {
+            "title": "McpStdioServerDefinition",
             "type": "object",
-            "additionalProperties": { "type": "string" }
-        },
-        "url": {
-            "description": "HTTP MCP endpoint URL.",
-            "type": "string",
-            "format": "uri",
-            "pattern": "^https?://"
-        },
-        "headers": {
-            "description": "HTTP request headers; values may reference ${ENV_NAME}. Authorization cannot also be configured here when authorization is set.",
-            "type": "object",
-            "additionalProperties": { "type": "string" }
-        },
-        "authorization": {
-            "description": "HTTP authentication. Secret fields reference the operator environment rather than embedding credentials.",
-            "oneOf": [
-                {
-                    "type": "object",
-                    "description": "Use a bearer token from the operator environment.",
-                    "additionalProperties": false,
-                    "required": ["type", "token"],
-                    "properties": {
-                        "type": { "const": "bearer" },
-                        "token": { "$ref": "#/$defs/environmentReference" }
-                    }
+            "additionalProperties": false,
+            "required": [
+                "name",
+                "type",
+                "command"
+            ],
+            "properties": {
+                "name": {
+                    "$ref": "#/$defs/name"
                 },
-                {
-                    "type": "object",
-                    "description": "Interactive OAuth using an HTTPS Client ID Metadata Document.",
-                    "additionalProperties": false,
-                    "required": ["type", "redirectUrl", "clientMetadataUrl"],
-                    "properties": {
-                        "type": { "const": "oauth" },
-                        "redirectUrl": { "type": "string", "format": "uri" },
-                        "clientMetadataUrl": {
-                            "type": "string",
-                            "format": "uri",
-                            "pattern": "^https://.+/.+"
-                        },
-                        "scope": { "type": "string", "minLength": 1 }
-                    }
+                "type": {
+                    "description": "A local server: a subprocess speaking MCP over its standard input and output.",
+                    "const": "stdio"
                 },
-                {
-                    "type": "object",
-                    "description": "Interactive OAuth using a pre-registered client ID and secret.",
-                    "additionalProperties": false,
-                    "required": ["type", "redirectUrl", "clientId", "clientSecret"],
-                    "properties": {
-                        "type": { "const": "oauth" },
-                        "redirectUrl": { "type": "string", "format": "uri" },
-                        "clientId": { "type": "string", "minLength": 1 },
-                        "clientSecret": { "$ref": "#/$defs/environmentReference" },
-                        "scope": { "type": "string", "minLength": 1 }
-                    }
+                "command": {
+                    "description": "An executable name or path, without a shell. Relative paths resolve against the working directory.",
+                    "type": "string",
+                    "minLength": 1
                 },
-                {
-                    "type": "object",
-                    "description": "Interactive OAuth using dynamic client registration.",
-                    "additionalProperties": false,
-                    "required": ["type", "redirectUrl"],
-                    "properties": {
-                        "type": { "const": "oauth" },
-                        "redirectUrl": { "type": "string", "format": "uri" },
-                        "scope": { "type": "string", "minLength": 1 }
+                "args": {
+                    "description": "Exact arguments; ${NAME} environment references expand once.",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
                     }
                 },
-                {
+                "env": {
+                    "description": "Process environment additions; ${NAME} references resolve against the workspace-composed operator environment.",
                     "type": "object",
-                    "description": "Noninteractive OAuth client-credentials grant; issuer optionally binds the credentials to an authorization server.",
-                    "additionalProperties": false,
-                    "required": ["type", "clientId", "clientSecret"],
-                    "properties": {
-                        "type": { "const": "client-credentials" },
-                        "clientId": { "type": "string", "minLength": 1 },
-                        "clientSecret": { "$ref": "#/$defs/environmentReference" },
-                        "scope": { "type": "string", "minLength": 1 },
-                        "issuer": { "type": "string", "minLength": 1 }
+                    "additionalProperties": {
+                        "type": "string"
                     }
-                }
-            ]
-        },
-        "tools": {
-            "description": "Exact enabled tool names; omitted enables all tools, an empty array enables none.",
-            "type": "array",
-            "uniqueItems": true,
-            "items": { "type": "string", "minLength": 1 }
-        },
-        "read": {
-            "description": "Exact tool names the operator designates as read effects rather than host effects requiring proposal review.",
-            "type": "array",
-            "uniqueItems": true,
-            "items": { "type": "string", "minLength": 1 }
-        }
-    },
-    "$defs": {
-        "environmentReference": {
-            "description": "An operator environment variable reference such as ${GITEA_TOKEN}, never a literal secret.",
-            "type": "string",
-            "pattern": "^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
-        }
-    },
-    "allOf": [
-        {
-            "if": {
-                "properties": { "transport": { "const": "stdio" } },
-                "required": ["transport"]
-            },
-            "then": {
-                "required": ["command"],
-                "not": {
-                    "anyOf": [
-                        { "required": ["url"] },
-                        { "required": ["headers"] },
-                        { "required": ["authorization"] }
-                    ]
+                },
+                "cwd": {
+                    "description": "An absolute working directory, optionally using ${NAME} references. When absent the host supplies a workspace-owned state directory outside the project.",
+                    "type": "string",
+                    "minLength": 1
                 }
             }
         },
-        {
-            "if": {
-                "properties": { "transport": { "const": "http" } },
-                "required": ["transport"]
-            },
-            "then": {
-                "required": ["url"],
-                "not": {
-                    "anyOf": [
-                        { "required": ["command"] },
-                        { "required": ["args"] },
-                        { "required": ["cwd"] },
-                        { "required": ["env"] }
+        "streamableHttp": {
+            "title": "McpStreamableHttpServerDefinition",
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "name",
+                "type",
+                "url"
+            ],
+            "properties": {
+                "name": {
+                    "$ref": "#/$defs/name"
+                },
+                "type": {
+                    "description": "A remote server: an MCP endpoint over Streamable HTTP.",
+                    "const": "streamable-http"
+                },
+                "url": {
+                    "description": "The explicitly configured HTTP(S) MCP endpoint. OAuth has its own transport-security requirements.",
+                    "type": "string",
+                    "pattern": "^https?://"
+                },
+                "headers": {
+                    "description": "Headers sent only to this endpoint; ${NAME} references expand at connection time. Protocol-owned headers are supplied by the client. Authorization cannot also be declared as a header when authorization is configured.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "authorization": {
+                    "title": "McpAuthorization",
+                    "description": "This endpoint's bearer or OAuth configuration. Secrets remain symbolic environment references.",
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "required": [
+                                "type",
+                                "token"
+                            ],
+                            "properties": {
+                                "type": {
+                                    "const": "bearer"
+                                },
+                                "token": {
+                                    "$ref": "https://schemas.plurnk.xyz/v0/McpOAuth.json#/$defs/environmentReference"
+                                }
+                            }
+                        },
+                        {
+                            "$ref": "https://schemas.plurnk.xyz/v0/McpOAuth.json"
+                        }
                     ]
                 }
             }
         }
-    ]
+    }
 }

package/dist/schema/SkillDefinition.json

@@ -2,10 +2,10 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schemas.plurnk.xyz/v0/SkillDefinition.json",
     "title": "SkillDefinition",
-    "description": "One standard Agent Skill: its name, source scope, and — for a workspace-installed skill — the standard installer package reference.",
+    "description": "One standard Agent Skill and its source. Source locations are inputs, not installation scopes.",
     "type": "object",
     "additionalProperties": false,
-    "required": ["name", "scope"],
+    "required": ["name"],
     "properties": {
         "name": {
             "description": "The standard Agent Skills name: Unicode lowercase or uncased letters and numbers joined by single hyphens, equal to the skill's directory name.",
@@ -13,14 +13,20 @@
             "pattern": "^(?!.*[\\p{Uppercase}\\p{Lt}])[\\p{L}\\p{N}]+(?:-[\\p{L}\\p{N}]+)*$",
             "maxLength": 64
         },
-        "scope": {
-            "description": "Source: project `.agents/skills`, global `~/.agents/skills`, or a service-provided resource tree. Service sources are not installer targets.",
-            "enum": ["project", "global", "service"]
-        },
         "source": {
-            "description": "The standard installer package reference (`owner/repo`, a git URL, or a local path) that provides the skill; required to add a skill that is not yet installed.",
+            "description": "A local skill folder or its SKILL.md (read in place), a Git remote, or an archive (materialized into workspace storage). Required for configured and added skills; omitted only for a host-provided tree.",
+            "type": "string",
+            "minLength": 1
+        },
+        "ref": {
+            "description": "The branch or tag of a git source; the remote's default branch when absent.",
             "type": "string",
             "minLength": 1
+        },
+        "commit": {
+            "description": "The commit a git source's ref named when the skill was added. The service records it; a client never supplies it.",
+            "type": "string",
+            "pattern": "^[0-9a-f]{40}(?:[0-9a-f]{24})?$"
         }
     }
 }