Package metadata

Beyond the tarball itself, mx publish writes structured metadata the registry can index for search and discovery. Two things travel alongside the tarball:

1. Discovery metadata — extracted from matrix.json and the built artifacts; published to the registry's discovery index.
2. Registry index entry — a versions[<version>] record under the package name, with publishedAt/publishedBy attribution.

Discovery metadata

The shape (packages/mx-cli/src/utils/discovery-extractor.ts:35-47):

interface IPackageDiscoveryMetadata {
  readonly packageName: string;
  readonly version: string;
  readonly displayName?: string;
  readonly description?: string;
  readonly declaredKind?: string;       // "webapp" | "service" | "library"
  readonly inferredKind: string;
  readonly tags: readonly string[];
  readonly capabilities: readonly string[];
  readonly permissions: JsonRecord | null;
  readonly webapp?: IWebappDiscoveryMetadata;
  readonly components: readonly IComponentDiscoveryMetadata[];
}

For each component:

interface IComponentDiscoveryMetadata {
  readonly type: string;
  readonly exportName?: string;
  readonly mount?: string;
  readonly surface?: string;
  readonly description?: string;
  readonly kind?: string;
  readonly accepts: readonly string[];
  readonly emits: readonly string[];
  readonly skills: readonly string[];
  readonly tags: readonly string[];
  readonly capabilities: readonly string[];
}

For the webapp surface (when present):

interface IWebappDiscoveryMetadata {
  readonly appName: string;
  readonly routePrefix?: string;
  readonly displayName?: string;
  readonly icon?: string;
  readonly navOrder?: number;
  readonly description?: string;
  readonly shells: readonly string[];
}

Where discovery metadata comes from

Mostly from matrix.json. Components carry an extra layer of static inspection:

• The extractor opens dist/index.js (or whichever entry resolves to the component) and reads the static metadata declared on each exported class.
• static accepts, static emits, static skills, static tags, static capabilities are merged with the manifest's components[].accepts/emits/etc.
• The static contract wins on conflict (the class is the ground truth; the manifest is advisory).

This is the contract spelled out in WORKSTREAMS/core-and-packaging/MATRIX-DISCOVERY-METADATA-SPEC.md.

Registry index entry

For local registries, publishRegistryVersion (packages/mx-cli/src/utils/registry-store.ts) writes:

{
  "packages": {
    "@open-matrix/chat": {
      "versions": {
        "0.2.9": {
          "tarballPath": "<registry-root>/@open-matrix/chat/0.2.9/chat-0.2.9.tar.gz",
          "publishedAt": "2026-05-05T16:00:00.000Z",
          "publishedBy": "richard.santomauro@nimbletec.com"
        }
      }
    }
  }
}

The discovery metadata for the same version is written next to the tarball as a JSON file the index references.

npm-compatible registries

For HTTP-backed npm registries, the metadata format is whatever the registry itself supports. npm publish (which mx publish shells out to) sends:

• The tarball (multipart payload).
• An npm-compatible package document with name, version, dist.tarball, dist.shasum.
• The package's own package.json is included in the tarball.

Discovery metadata for npm-backed registries is currently a Matrix- specific extension; HiveCast's Gitea registry stores it as an auxiliary JSON document. See Gitea-backed publication.

What goes in the tarball vs the metadata

Goes in the tarball	Goes in the metadata
dist/ (built artifacts)	Component list, accepts/emits
matrix.json	Webapp surface (appName, route prefix)
matrix.service.json	Permissions snapshot
package.json	Discovery tags / capabilities
Files listed under package.json:files	Display name / description
LICENSE, README.md	Inferred + declared kind

The tarball is what gets installed. The metadata is what registry search uses to find the package.

See also

• Publishing → Versioning
• Publishing → Gitea-backed publication
• Publishing → npm-compatible publication
• Reference → Package metadata schema

Source: projects/matrix-3/packages/mx-cli/src/utils/discovery-extractor.ts defines the metadata shape; packages/mx-cli/src/utils/discovery-index.ts publishes it; packages/mx-cli/src/utils/registry-store.ts writes the local-registry index entry.