How the Catalog works

The Catalog is the named inventory of Templates and Mixins you use by ref, such as template:backend-api or mixin:documentation. Every Atomize tool reads it through the same Template Library, from three scopes:

Scope	Where it lives	Shown as	Who changes it
Built-in	Ships with Atomize	built-in	Nobody: it's read-only
Personal (--scope user)	~/.atomize/catalog	personal	You, on this computer
Project (--scope project)	.atomize/catalog in the Workspace Root	your project	Anyone who changes the repository

Each scope keeps Templates in a templates folder and Mixins in a mixins folder. A Template is runnable: you preview and generate with it, and it can extends another Template. A Mixin only contributes tasks to the Templates that list it under mixins:, so it can't be previewed or generated on its own. See Composition.

Workspace Root

Project scope belongs to the Workspace Root: the nearest folder above where you're working that has a .atomize folder, otherwise the git repository's root, otherwise the folder itself. The .atomize folder in your home folder never counts, because it holds your Connection Profiles and personal Catalog.

A Workspace Root with its own .atomize folder has opted in to a project Catalog. There, the CLI installs and saves to project scope by default, and VS Code offers the Project Catalog first. Without that folder, they default to your personal Catalog.

Precedence And Catalog Overrides

When two items of the same kind share a name, project scope wins over personal, and personal wins over built-in. The winner is what template:<name> or mixin:<name> resolves to, and the other item is overridden. atomize template list and VS Code's Atomize: Browse Catalog mark the winner with ⚠ overrides and the overridden item's scope and path:

  backend-api
    Backend API (Contoso)
    Standard backend API development with database integration
    ref: template:backend-api  scope: your project
    path: ~/src/contoso-app/.atomize/catalog/templates/backend-api.atomize.yaml
    ⚠ overrides: built-in at <Atomize>/catalog/templates/backend-api.atomize.yaml (read-only)

Override on purpose, for example to adapt a built-in Template for one project without renaming it. Give the item its own name when you want to keep both.

Template Lineage

A Template or Mixin's origin field records the Catalog item it was derived from, as template:<name> or mixin:<name>. Lineage is informational: it never changes how refs resolve, and the derived item doesn't override its origin. Lists show it as ↖ based on:

  mobile-feature
    Mobile Feature
    Feature breakdown with device testing
    ref: template:mobile-feature  scope: your project
    path: ~/src/contoso-app/.atomize/catalog/templates/mobile-feature.atomize.yaml
    ↖ based on: built-in template:feature-development

A flat copy from atomize template create --from, atomize template improve --save-as, and VS Code's Save Improvement as New Template record origin for you.

Continue

Create a Template, install and manage Catalog items, or share Templates with your team. To combine Catalog items, see Compose Templates.