@openship/protocol 0.0.2 → 0.0.3

package/dist/package-meta.json

@@ -1,7 +1,7 @@
 {
   "openship": "1.0",
   "package": "@openship/protocol",
-  "packageVersion": "0.0.2",
+  "packageVersion": "0.0.3",
   "source": "https://github.com/openshipdev/openship/tree/main/skills/openship",
-  "sourceCommit": "9d6c35e78bae95a368220beea241a214aa0f24f3"
+  "sourceCommit": "dc28f02cd0608b2669c1f16135e4b04a59c96773"
 }

package/dist/skill/references/examples/invalid/discovery-mcp.json

@@ -2,8 +2,14 @@
   "openship": "1.0",
   "capability": "discovery",
   "project": { "name": "Broken MCP", "description": "The MCP URL is not absolute HTTPS." },
+  "agent": {
+    "summary": "OpenShip exposes capabilities for a running project.",
+    "instructions": "Fetch and read agent.skill before using any capability.",
+    "skill": "https://example.com/openship/file/skills/openship/SKILL.md"
+  },
   "capabilities": {
     "sources": {
+      "description": "Retrieve and verify the exact source snapshot published by this deployment.",
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
       "mcp": "/mcp"

package/dist/skill/references/examples/invalid/discovery.json

@@ -2,12 +2,17 @@
   "openship": "1.0",
   "capability": "discovery",
   "project": { "name": "Broken", "description": "Sources is missing." },
+  "agent": {
+    "summary": "OpenShip exposes capabilities for a running project.",
+    "instructions": "Fetch and read agent.skill before using any capability.",
+    "skill": "https://example.com/openship/file/skills/openship/SKILL.md"
+  },
   "capabilities": {
     "changes": {
+      "description": "Submit a patch against a published source digest.",
       "policy": "https://example.com/openship/policy.json",
       "submit": "https://example.com/openship/changes",
       "status": "https://example.com/openship/changes/{changeId}"
     }
   }
 }
-

package/dist/skill/references/examples/valid/discovery.json

@@ -2,9 +2,15 @@
   "openship": "1.0",
   "capability": "discovery",
   "project": { "name": "Example", "description": "An example OpenShip project." },
-  "skill": "https://example.com/openship/file/skills/openship/SKILL.md",
+  "agent": {
+    "summary": "OpenShip lets this running project publish verifiable source code and optionally accept isolated changes or describe its complete system.",
+    "instructions": "Fetch and read agent.skill before interpreting or using any advertised capability. Resolve relative links in the skill against the skill URL.",
+    "skill": "https://example.com/openship/file/skills/openship/SKILL.md"
+  },
+  "page": "https://example.com/openship",
   "capabilities": {
     "sources": {
+      "description": "Retrieve and verify the exact source snapshot published by this deployment.",
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
       "mcp": "https://mcp.example.com/mcp",
@@ -12,6 +18,7 @@
       "archive": "https://example.com/openship/source.tar.gz"
     },
     "changes": {
+      "description": "Submit a patch against the published source digest and inspect an isolated candidate result.",
       "policy": "https://example.com/openship/policy.json",
       "submit": "https://example.com/openship/changes",
       "status": "https://example.com/openship/changes/{changeId}"

package/dist/skill/references/openship-mcp.md

@@ -13,6 +13,7 @@ A producer MAY advertise an absolute HTTPS Streamable HTTP endpoint as `capabili
 {
   "capabilities": {
     "sources": {
+      "description": "Retrieve and verify the exact source snapshot published by this deployment.",
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
       "mcp": "https://mcp.example.com/mcp"

package/dist/skill/references/openship.md

@@ -56,9 +56,15 @@ The response MUST be unauthenticated JSON, MUST allow cross-origin reads with `A
     "name": "Example",
     "description": "A short description of the running project."
   },
-  "skill": "https://example.com/openship/file/skills/openship/SKILL.md",
+  "agent": {
+    "summary": "OpenShip lets this running project publish verifiable source code and optionally accept isolated changes or describe its complete system.",
+    "instructions": "Fetch and read agent.skill before interpreting or using any advertised capability. Resolve relative links in the skill against the skill URL.",
+    "skill": "https://example.com/openship/file/skills/openship/SKILL.md"
+  },
+  "page": "https://example.com/openship",
   "capabilities": {
     "sources": {
+      "description": "Retrieve and verify the exact source snapshot published by this deployment.",
       "manifest": "https://example.com/openship/manifest.json",
       "bundle": "https://example.com/openship/bundle.json",
       "mcp": "https://mcp.example.com/mcp",
@@ -67,11 +73,13 @@ The response MUST be unauthenticated JSON, MUST allow cross-origin reads with `A
       "instructions": "https://example.com/openship/agent.txt"
     },
     "changes": {
+      "description": "Submit a patch against the published source digest and inspect an isolated candidate result.",
       "policy": "https://example.com/openship/policy.json",
       "submit": "https://example.com/openship/changes",
       "status": "https://example.com/openship/changes/{changeId}"
     },
     "systems": {
+      "description": "Retrieve a self-contained description of this project’s source, architecture, infrastructure, and agent context.",
       "document": "https://example.com/openship/system.json"
     }
   }
@@ -80,20 +88,46 @@ The response MUST be unauthenticated JSON, MUST allow cross-origin reads with `A
 
 Requirements:
 
-- `project`, `capabilities`, and `capabilities.sources` are REQUIRED.
+- `project`, `agent`, `capabilities`, and `capabilities.sources` are REQUIRED.
 - `project.name` and `project.description` are REQUIRED.
+- `agent.summary`, `agent.instructions`, and `agent.skill` are REQUIRED. The summary MUST explain OpenShip in standalone plain language. The instructions MUST explicitly direct an unfamiliar agent to fetch and read `agent.skill` before interpreting or using the capability links.
+- `agent.skill` MUST identify the OpenShip skill entry point. Relative links in that skill MUST be resolved against the skill URL.
+- Every advertised capability MUST contain a standalone `description` explaining what the capability lets an agent do.
 - `sources.manifest` and `sources.bundle` are REQUIRED.
 - `sources.mcp` is OPTIONAL and, when present, advertises the OpenShip Sources MCP binding.
-- `changes`, `systems`, and `skill` are OPTIONAL and MUST be omitted when unavailable.
+- `changes` and `systems` are OPTIONAL and MUST be omitted when unavailable.
+- `page` is OPTIONAL and, when present, MUST be an absolute HTTPS URL for a human- and agent-readable presentation of this OpenShip origin.
 - Changes MUST NOT be advertised without Sources.
 - `file` and `status` are URI templates with exactly the named expansion.
 - A project implementing Sources and Changes but not Systems simply omits `capabilities.systems`.
 
 See [schemas/discovery.schema.json](schemas/discovery.schema.json).
 
+### Optional `/openship` presentation route
+
+A website MAY serve `GET /openship` and advertise its absolute URL in discovery as `page`. This
+route is a presentation aid for agents and humans. It does not replace
+`/.well-known/openship.json`, and its absence does not affect conformance.
+
+When implemented, the route MUST:
+
+- identify itself as the project’s OpenShip page and explain OpenShip in plain language;
+- show the project name and description and list every advertised capability with its meaning;
+- tell an unfamiliar agent to start with discovery and read `agent.skill` before acting;
+- link to discovery, the skill, and every advertised capability document or instruction URL;
+- for Sources, show the current snapshot digest, file count, and byte count from the Manifest;
+- for Changes, state whether submissions are currently accepted and make clear that a candidate result is not a production deployment; and
+- distinguish explanatory page content from the authoritative JSON documents.
+
+The route MAY use HTML or plain text. It MUST be publicly readable without authentication and
+SHOULD keep its essential explanation and links available as semantic text rather than requiring
+client-side interaction.
+
 ## Access and transport
 
-Discovery, Sources, and Systems reads MUST NOT require cookies, credentials, custom headers, or query parameters. Changes writes MAY require authorization or payment disclosed by the Changes policy.
+Discovery, `agent.skill`, the skill’s referenced documents, Sources, and Systems reads MUST NOT
+require cookies, credentials, custom headers, or query parameters and MUST allow cross-origin reads.
+Changes writes MAY require authorization or payment disclosed by the Changes policy.
 
 JSON responses MUST use UTF-8. Public reads SHOULD support transport compression. A producer MAY offer additional representations, but the advertised JSON representation remains normative.
 

package/dist/skill/references/schemas/discovery.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://openship.dev/schemas/discovery.schema.json",
   "title": "OpenShip v1 discovery",
   "type": "object",
-  "required": ["openship", "capability", "project", "capabilities"],
+  "required": ["openship", "capability", "project", "agent", "capabilities"],
   "properties": {
     "openship": { "const": "1.0" },
     "capability": { "const": "discovery" },
@@ -16,15 +16,26 @@
       },
       "additionalProperties": true
     },
-    "skill": { "$ref": "#/$defs/httpsUrl" },
+    "agent": {
+      "type": "object",
+      "required": ["summary", "instructions", "skill"],
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "instructions": { "type": "string", "minLength": 1 },
+        "skill": { "$ref": "#/$defs/httpsUrl" }
+      },
+      "additionalProperties": true
+    },
+    "page": { "$ref": "#/$defs/httpsUrl" },
     "capabilities": {
       "type": "object",
       "required": ["sources"],
       "properties": {
         "sources": {
           "type": "object",
-          "required": ["manifest", "bundle"],
+          "required": ["description", "manifest", "bundle"],
           "properties": {
+            "description": { "type": "string", "minLength": 1 },
             "manifest": { "$ref": "#/$defs/httpsUrl" },
             "bundle": { "$ref": "#/$defs/httpsUrl" },
             "mcp": { "$ref": "#/$defs/httpsUrl" },
@@ -36,8 +47,9 @@
         },
         "changes": {
           "type": "object",
-          "required": ["policy", "submit", "status"],
+          "required": ["description", "policy", "submit", "status"],
           "properties": {
+            "description": { "type": "string", "minLength": 1 },
             "policy": { "$ref": "#/$defs/httpsUrl" },
             "submit": { "$ref": "#/$defs/httpsUrl" },
             "status": { "type": "string", "pattern": "^https://.+\\{changeId\\}.+$|^https://.+/\\{changeId\\}$" }
@@ -46,8 +58,11 @@
         },
         "systems": {
           "type": "object",
-          "required": ["document"],
-          "properties": { "document": { "$ref": "#/$defs/httpsUrl" } },
+          "required": ["description", "document"],
+          "properties": {
+            "description": { "type": "string", "minLength": 1 },
+            "document": { "$ref": "#/$defs/httpsUrl" }
+          },
           "additionalProperties": true
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openship/protocol",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Canonical OpenShip 1.0 types, validators, consumer helpers, schemas, and skill assets.",
   "type": "module",
   "license": "MIT",

package/src/index.d.ts

@@ -8,7 +8,8 @@ export const OPENSHIP_MCP_FILE_RESOURCE_TEMPLATE: "openship://sources/file{?path
 export interface SourceFileMetadata { path: string; size: number; sha256: string; encoding: OpenShipEncoding; mediaType: string; type: "file" | "symlink"; target?: string; [key: string]: unknown }
 export interface SourcesManifest { openship: "1.0"; capability: "sources"; digest: string; project: { name: string; description: string; [key: string]: unknown }; totals: { files: number; bytes: number; [key: string]: unknown }; files: SourceFileMetadata[]; [key: string]: unknown }
 export interface SourcesBundle { openship: "1.0"; capability: "sources"; digest: string; files: Record<string, { encoding: OpenShipEncoding; content: string; [key: string]: unknown }>; [key: string]: unknown }
-export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; capabilities: { sources: { manifest: string; bundle: string; mcp?: string; [key: string]: unknown }; systems?: { document: string; [key: string]: unknown }; changes?: { policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
+export interface DiscoveryAgent { summary: string; instructions: string; skill: string; [key: string]: unknown }
+export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; agent: DiscoveryAgent; page?: string; capabilities: { sources: { description: string; manifest: string; bundle: string; mcp?: string; [key: string]: unknown }; systems?: { description: string; document: string; [key: string]: unknown }; changes?: { description: string; policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
 export type SystemsNodeKind = "Root" | "Host" | "Container" | "Process" | "Library";
 export type SystemsNodeOwnership = "first_party" | "third_party";
 export interface SystemsNodeMetadata { ownership: SystemsNodeOwnership; [key: string]: unknown }

package/src/index.js

@@ -179,24 +179,43 @@ export function validateSources(manifestValue, bundleValue, options = {}) {
 
 export function validateDiscovery(value) {
   const discovery = envelope(value, "discovery");
+  const absoluteUrl = (value, path) => {
+    const raw = string(value, path);
+    let url;
+    try { url = new URL(raw); } catch { fail(path, "must be an absolute HTTPS URL"); }
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) fail(path, "must be an absolute HTTPS URL outside local development");
+    return raw;
+  };
   const project = object(discovery.project, "$.project");
   string(project.name, "$.project.name");
   string(project.description, "$.project.description");
+  const agent = object(discovery.agent, "$.agent");
+  string(agent.summary, "$.agent.summary");
+  string(agent.instructions, "$.agent.instructions");
+  absoluteUrl(agent.skill, "$.agent.skill");
+  if (discovery.page !== undefined) absoluteUrl(discovery.page, "$.page");
   const capabilities = object(discovery.capabilities, "$.capabilities");
   const sources = object(capabilities.sources, "$.capabilities.sources");
-  const absoluteUrl = (value, path) => {
-    const url = string(value, path);
-    try { new URL(url); } catch { fail(path, "must be an absolute URL"); }
-    return url;
-  };
+  string(sources.description, "$.capabilities.sources.description");
   for (const key of ["manifest", "bundle"]) {
-    const url = string(sources[key], `$.capabilities.sources.${key}`);
-    try { new URL(url); } catch { fail(`$.capabilities.sources.${key}`, "must be an absolute URL"); }
+    absoluteUrl(sources[key], `$.capabilities.sources.${key}`);
+  }
+  for (const key of ["mcp", "archive", "instructions"]) {
+    if (sources[key] !== undefined) absoluteUrl(sources[key], `$.capabilities.sources.${key}`);
+  }
+  if (sources.file !== undefined) {
+    absoluteUrl(sources.file, "$.capabilities.sources.file");
+    if (!String(sources.file).includes("{path}")) fail("$.capabilities.sources.file", "must contain {path}");
+  }
+  if (capabilities.systems) {
+    const systems = object(capabilities.systems, "$.capabilities.systems");
+    string(systems.description, "$.capabilities.systems.description");
+    absoluteUrl(systems.document, "$.capabilities.systems.document");
   }
-  if (sources.mcp !== undefined) absoluteUrl(sources.mcp, "$.capabilities.sources.mcp");
-  if (capabilities.systems) absoluteUrl(object(capabilities.systems, "$.capabilities.systems").document, "$.capabilities.systems.document");
   if (capabilities.changes) {
     const changes = object(capabilities.changes, "$.capabilities.changes");
+    string(changes.description, "$.capabilities.changes.description");
     for (const key of ["policy", "submit", "status"]) absoluteUrl(changes[key], `$.capabilities.changes.${key}`);
     if (!String(changes.status).includes("{changeId}")) fail("$.capabilities.changes.status", "must contain {changeId}");
   }