Appearance
Overview
The Overview section pins the vocabulary. Every other section in this domain assumes these distinctions; if you skim past, the Reference section will read as a pile of overlapping terms.
Three questions, three surfaces
The substrate must answer three different discovery questions (THESIS Part 3):
| Question | Surface | Authority |
|---|---|---|
| Q1. What can do X? Capability search across tiers and registries. | Catalog | system.catalog, ranking factors: capability match, stats, trust, cost, locality |
| Q2. What is in registry X? Browse the underlying registry. | Browse | Gitea HTTP, npm HTTP, etc. |
| Q3. What is currently live? What is mounted in this Space right now. | Live actor registry | system.registry |
Catalog and Browse can target the same registry. They answer different questions: Catalog is "what could be used"; Browse is "what is available under this registry"; Live is "what is happening right now."
The four authorities (disambiguation)
The codebase uses the words "registry" and "catalog" for four different things:
| Page | One-line question |
|---|---|
| Registry vs catalog | What is the difference between a registry and a catalog in Matrix? |
| Artifact registry | Gitea is the Matrix-native registry. Where do install bytes come from? |
| Package catalog | What is the metadata surface that answers "what can I install?" |
| Live actor registry | What is system.registry and what does it actually track? |
| System catalog | What is system.catalog and why is it different from system.registry? |
Quick decision tree
Are you asking about installable bytes (.tgz, .tar.gz)?
-> Artifact registry — Gitea (Matrix-native) or npm-compatible mirror
Are you asking about installable metadata (description, kind, accepts, emits)?
-> Package catalog — system.packages, discovery-index.json
Are you asking which mounts are live in this Host RIGHT NOW?
-> Live actor registry — system.registry
Are you asking for a unified read-only view of "what is mounted, where, with what ops"?
-> System catalog — system.catalog (read projection over registry + runtimes + gateway + introspect)Gitea is the Matrix-native registry
Gitea hosts the package artifacts and serves them through an npm-compatible HTTP API. New code, specs, and UI copy say "Gitea registry"; older docs may have said "Docker Hub" or "publish to npmjs.com" and those references are wrong for the Matrix-native path. Gitea is what hivecast install gitea://owner/repo@version resolves against.
The npm-shape compatibility exists so existing tooling (npm, pnpm) can publish and consume Matrix packages. The Matrix-native registry is Gitea; the wire format is npm. Both can be true.
If you find yourself reaching for "registry" without knowing which of the four, re-read Registry vs catalog. The Matrix codebase will not forgive the conflation.