> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/the-catalog-install-fork-upgrade.md).

# The catalog: install, fork, upgrade

Nobody should start from an empty agent editor. The controller image ships a **bundled catalog** of agent definitions and flow templates at `/var/lib/visdom/catalog/`, and new versions arrive through ordinary controller releases rather than through a download at runtime.

The catalog is signed. `catalog.lock` holds one `<sha256> <path>` line per manifest, `catalog.sig` is an Ed25519 signature over those bytes, and the release public key is compiled into the controller binary. The loader reconciles the manifests on boot and **refuses a catalog whose signature does not verify**. In local development that usually means somebody edited a manifest and forgot to re-sign it. Rotating the signing key is a new release, not a config change.

## What ships in v1

Ten agents across four categories, plus five flow templates.

* **code-review**: `code-review.general`, `code-review.security`
* **code-author**: `code-author.implement-from-spec`, `code-author.refactor`, `qa.test-author`
* **research**: `research.context-gatherer`, `research.spec-summariser`, `research.dependency-analyser`, `docs.changelog-author`, `ops.log-triage`
* **flows**: `ad-hoc-research`, `pr-review`, `security-audit`, `release-notes`, `bug-triage`

There is also a `base.claude` agent whose whole purpose is to be forked: a generic Claude runtime with no ports declared, meant as the starting point for something new.

## Install versus fork

The two words are not interchangeable.

* **Install** applies to a *flow template*. It creates a flow in your project from the template, with the parameter values you supply, and records an installation row pointing back at the catalog manifest.
* **Fork** applies to an *agent definition*. It copies the definition into your workspace as an editable agent and records a fork row with the same back-pointer.

Both records carry `catalog_ref`, the manifest's `(name, version)`, plus who did it, when, and which versions have been dismissed.

{% hint style="success" %}
**Order matters when a flow contains a loop over a sub-flow.** The materialiser resolves a `sub_flow_name` against flows already installed in the same project and rewrites it to a real id. Install the inner flow first, or the outer one will not materialise.
{% endhint %}

## Upgrades are proposed, never applied

A scanner compares each installation and fork against the catalog and raises a notification when a newer manifest version exists. Three things can then happen to that notification: **adopted**, **applied**, or **dismissed**. A dismissed version is remembered per record, so the same upgrade does not keep reappearing.

Nothing auto-adopts. This is deliberate: a forked agent is usually edited immediately after forking, and silently pulling a new upstream version would discard exactly the work that made it useful.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-orchestrator/user-guide/the-catalog-install-fork-upgrade.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.