Own Macro Registry Guide

This guide shows how to build and maintain your own local ProtoML macro registry, publish packs into it, and consume those packs from a project meeting file.

What this workflow is for

Use a custom macro registry when you want a reusable, curated macro catalog for one team, one company, or one document domain instead of copying macro files between repositories.

This guide is about macro package registries only. It is not about protoparser register "<dir>", which creates governance and status reports for document collections.

Where a company registry can live

a simple internal web server that serves protoml.registry.json and pack files over HTTP or HTTPS
a shared local path such as Z:\protoml-registry or /mnt/protoml-registry
an intranet static host or normal artifact/file server

You do not need a special registry backend. A company registry can be just static JSON plus files on a plain web server or network path.

Choose the right trust path first

Use bundled {{macro_dir}} macros first when the shipped macro set already covers the need
Use a registry when you need reusable custom packs across multiple projects or teams
Use detached signatures plus a registry when your custom macros should resolve to trusted
Use unsigned local macros only for exploratory work where unknown is acceptable

Create the registry

protoparser macro_install init_registry "./my-registry"

This creates the local registry root and the protoml.registry.json index file.

Create a pack inside the registry

protoparser macro_install init_pack "meeting-kit" "./my-registry"

This gives you a pack folder with a protoml-pack.json manifest and a place for the pack's macro files.

Add macros to the pack

Place your custom macro files into the pack and describe the pack in its manifest. A simple macro could look like this:

@new_macro
=name:decisionCard
=docs:
Renders a highlighted decision summary.
=template:
<div class="decision-card">
  <strong>{{title}}</strong><br>
  {{text}}
</div>

Add the pack to the registry index

protoparser macro_install registry_add "./my-registry" "./my-registry/packs/meeting-kit"

If the pack changes later, refresh the registry entry with:

protoparser macro_install registry_update "./my-registry" "./my-registry/packs/meeting-kit"

Connect a project to your registry

protoparser macro_install init
protoparser macro_install add_registry "./my-registry"

This prepares the project-local macro configuration and adds your registry as a source.

Install or sync a pack from the registry

protoparser macro_install add_package "meeting-kit" 1.0.0
protoparser macro_install sync

Or install in one step:

protoparser macro_install install "meeting-kit" 1.0.0

The project then receives the installed files in .protoml/macro-packs/ and a generated macros.index.pml.

Bind the registry macros into a meeting file

@macros_import ".protoml/macro-packs/macros.index.pml"
@protocol "Architecture Review - {{date}}"

@participants
=lead:Jane Doe,jdoe,jdoe@example.com

@meeting "Architecture Review"
# Decisions
@@macro=decisionCard:title=Storage;text=Use the replicated storage tier

This is the meeting-side integration step: the generated macro index exposes the installed macros, and the meeting document uses them with @@macro=....

Manage installed packs in a project

List installed packs: protoparser macro_install list
Inspect a pack: protoparser macro_install info "meeting-kit"
Change the requested version: protoparser macro_install update_package "meeting-kit" 1.1.0
Remove the package definition: protoparser macro_install remove_package "meeting-kit"
Uninstall and remove a pack from the project: protoparser macro_install remove "meeting-kit"

Manage the registry itself

Add a pack entry: registry_add
Refresh a changed pack entry: registry_update
Remove a pack entry: protoparser macro_install registry_remove "./my-registry" "meeting-kit"

Removing a pack from the registry index stops future resolution through that registry entry, but existing project installs may still keep local copies until updated or removed.

Signing workflow for registry macros

If you want a registry-delivered macro to become trusted in the ProtoML trust workflow, the macro file itself must be signed and the signing author must be listed in the registry authors section.

protoparser sign macro "./my-registry/packs/meeting-kit/macros/meeting_kit_sample.pml" "./keys/alice-private.pem" "Alice" alice-main

This creates a detached *.sig.json file next to the macro. The registry then needs a matching trusted author entry:

{
  "version": 1,
  "name": "my-registry",
  "authors": [
    {
      "name": "Alice",
      "trust": "trusted",
      "keys": [
        {
          "id": "alice-main",
          "public_key": "-----BEGIN PUBLIC KEY----- ..."
        }
      ]
    }
  ],
  "packages": []
}

After that, consumers can run verify or trust with -trustRegistry=... and the macro can resolve to trusted if it has no hard risk flags such as JavaScript or external URLs.

Registries can be split or combined

A ProtoML registry does not have to do everything at once. A registry may publish:

package entries in packages for install, sync, and search workflows
author trust entries in authors for trust, verify, and validate workflows
or both in one combined registry

That means teams can keep macro delivery in one registry and trusted authors in another if that better matches their release and security process.

Recommended trust-aware workflow

Start with bundled macros when possible
Create a custom pack only for the gaps
Sign the pack macros before treating them as production-ready
Publish the signing authors in the registry authors list
Install the pack into the project and check it with trust, verify, or validate -trust=...
Review JavaScript and external URLs explicitly, even for signed registry macros

What about built-in macros?

Bundled built-in macros can resolve to trusted without detached sidecars when they match the shipped built-in hash manifest and do not trigger hard risk flags.

If built-in macros should participate in the exact same author-signature workflow as external macros, they still need detached signatures and a matching trusted author entry in a documented trust registry. Extra or modified files in the built-in macro directory are not automatically trusted.

Detached sidecar workflow without a registry

Not every signed macro has to live inside a registry.

Author side:

sign the standalone macro file with protoparser sign macro ...
ship the macro together with its *.sig.json sidecar
ship the public key through a documented channel

User side:

keep the macro and sidecar together
run protoparser verify macro ...
treat the result as cryptographic verification, not as automatic registry trust

Remote registries

ProtoML can already use remote registry URLs for discovery, trust lookup, and explicit search. The remote workflow is intentionally simple: the registry is just a JSON document plus reachable pack files behind normal HTTP or HTTPS URLs.

What the registry admin must do

Host a protoml.registry.json file on a stable HTTP or HTTPS URL
Publish each pack at a stable remote location and make sure the registry source and manifest paths point to reachable files
Keep package versions immutable once published whenever possible
Optionally publish an authors list with trusted or untrusted authors and public keys for trust verification
Document whether the registry is public, internal, reviewed, or experimental

A minimal remote registry usually looks like a static website, GitHub Pages site, internal web server, or artifact host that serves JSON and pack files without any special server logic.

What the user must do

Add the remote registry to the project with protoparser macro_install add_registry "https://example.org/protoml.registry.json" if it should be part of the project config
Search it explicitly with protoparser macro_install search "meeting" "https://example.org/protoml.registry.json" if it should only be queried ad hoc
Use repeatable -trustRegistry=... flags with trust, verify, or validate -trust=... when one or more registries should act as author trust sources
Review the registry owner and pack maintainers before treating the registry as trusted

Local company registry variant

Some teams do not want HTTP hosting at all. In that case, the same registry can live in a shared directory or mounted network path.

protoparser macro_install add_registry "Z:\protoml-registry"
protoparser macro_install add_registry "/mnt/protoml-registry"
protoparser validate "./governance/release-checklist.pml" -trust=strict -trustRegistry="Z:\protoml-registry"

This works well for internal-only environments where a reviewed file share or NFS path is easier to operate than a hosted web endpoint.

Operational notes

Remote registries are best for discovery and trust lookup first
For controlled environments, teams should still prefer a reviewed internal registry
If a remote registry changes frequently, consumers should pin versions in protoml.macros.json
Trust classification still comes from risk flags, signatures, and author trust, not from the fact that a registry happens to be remote

Recommended maintenance flow

Create or edit macros inside a pack
Update the pack version when behavior meaningfully changes
Refresh the registry entry
Update consuming projects and run sync
Render HTML and verify the macro output in a real document

Practical advice

Keep packs focused on one domain such as meetings, approvals, finance, or legal output
Prefer semantic macro names that still make sense outside the original project
Use a local registry first before introducing remote distribution
Inspect the generated project macro index after pack changes