Documentation links

The catalog does not currently surface a typed documentation field. Package documentation reaches consumers via three indirect paths:

1. README in the tarball. Standard npm convention: README.md is included in published tarballs, rendered by IDEs and registry frontends. Gitea renders it on the package page.
2. package.json.homepage and package.json.repository. These are npm-canonical fields that npm UIs display. The Matrix catalog does not re-store them; consumers read package.json directly.
3. The new docs- packages.* Cross-cutting documentation lives in dedicated docs packages (@open-matrix/docs-registry, @open-matrix/docs-gateway, @open-matrix/docs-hivecast, etc.). Each is a normal Matrix webapp package shipped through the registry; consumers install and view them like any other app.

What the catalog surfaces today

// IPackageDiscoveryMetadata
{
  packageName, version, displayName, description,
  inferredKind, declaredKind, tags, capabilities,
  webapp, components,
}

No documentation, homepage, readme, or links field. The description field is the closest thing — and it is intentionally one line.

Why this is OK today

• package.json.homepage is on every npm package.
• README.md is in every tarball.
• Docs packages are themselves searchable through the catalog (they have inferredKind: webapp, so they appear in any app surface query).

For the current product surface, that combination has been adequate: a search turns up @open-matrix/docs-gateway, the consumer installs it, the docs are served like any webapp.

Target state

The discovery-metadata spec mentions a future links block:

// Target state, not in code yet
links?: {
  documentation?: string;   // URL or relative docs package reference
  homepage?: string;
  repository?: string;
  issues?: string;
};

When that lands, search/list views can show "Open docs" / "Open homepage" links without each consumer having to re-read package.json. The Director and dashboard surfaces will benefit most.

This is not in code today.

Recommendations for package authors

• Keep package.json.homepage and package.json.repository filled in. Standard npm tooling and Gitea will render them.
• Ship a meaningful README.md in the tarball. The npm "files" array must include "README.md" (the npm publish safety audit calls out 9 packages currently missing the "files" field — fix those first).
• If the package has a corresponding docs package (e.g. @open-matrix/foo ↔ @open-matrix/docs-foo), name them in parallel scopes so the convention is discoverable.

See also

• Metadata
• npm Publish Safety Audit

Source: No documentation-typed field in projects/matrix-3/packages/system-catalog/src/SystemPackageRegistryActor.ts today. Target state lives in the discovery-metadata spec.