Registry Format

Manifest

Every item declares itself through an item.json file at the root of its source directory. Below is the real manifest for the Button component.

{
    "name": "button",
    "type": "registry:component",
    "title": "Button",
    "description": "Displays a button or link with variants, sizes, loading and an optional animated arrow.",
    "version": "1.2.1",
    "license": "open",
    "stability": "stable",
    "knowledge": {
        "keywords": ["action", "submit", "call to action"],
        "useWhen": ["Triggering an immediate action such as saving or submitting."],
        "avoidWhen": ["Representing a persistent on/off value; use switch or checkbox."],
        "related": ["button-group", "toggle"]
    },
    "registryDependencies": [],
    "dependencies": {
        "composer": ["jml/brok:^0.2"],
        "npm": []
    },
    "files": [
        {
            "path": "ui/button/button.blade.php",
            "target": "resources/views/components/ui/button.blade.php",
            "type": "blade"
        }
    ],
    "meta": {
        "a11y": "wcag-2.2-aa-target",
        "responsive": true,
        "rtl": true,
        "darkMode": true,
        "localized": true
    }
}

Field reference

The build pipeline

php artisan registry:build (the BuildRegistry command in apps/docs-registry) runs in four stages:

1. Scan — walks every registry/<tier>/<kind>/<name>/item.json and loads the manifest.
2. Validate — checks that every declared source file exists, targets stay inside the allowed path set, license flags match the tier, and open items carry no pro dependencies.
3. Inline — reads each source file and embeds its UTF-8 content plus a sha256 hash directly into the published JSON so the CLI can detect transport corruption after download. (The hash is co-shipped with the content, so it guards against accidental drift, not a tampered registry — see the integrity note below.)
4. Write — emits public/r/<tier>/<name>.json per item and a tier-level public/r/<tier>/registry.json index.

On the consumer side, ui:add <name> fetches the item JSON from the registry endpoint, writes each files[].target into the app, resolves registryDependencies recursively (a cycle guard prevents infinite loops), wires any JS files into resources/js/ui/index.js, and records the installed version in ui-lock.json.

Three places must stay in sync

A registry item is only fully "done" when it exists in all three of the following locations simultaneously. Guard tests (CatalogNavigationTest, MirrorParityTest, BlockRenderTest) enforce parity in CI and fail fast when any location is missing.

Validation rules

The build command rejects any manifest that violates the following rules. All checks also run with --dry-run so you can validate without writing output files.

• — Every declared file must exist. Each files[].path is resolved against the item source directory; the build fails if the file is missing.
• — Open items may not depend on pro items. Any slug in registryDependencies is checked against the tier of the dependency; cross-tier references from open → pro are rejected.
• — Targets must stay under allowed paths. Valid prefixes are resources/views/components/ui, resources/views/blocks, resources/views/pages, resources/js/ui, resources/css/themes, and public/vendor/brok. Any other target path is rejected.
• — Published files carry SHA-256 hashes and inlined content. The build computes a sha256 of each source file and embeds both the hash and the full file content in the published JSON. The CLI recomputes the hash on write and aborts on a mismatch. Because the hash is co-shipped with the content, this catches transport corruption and accidental drift — by itself it is not a defence against a tampered or malicious registry (an attacker who can alter the response can recompute a matching hash), and unpinned consumers rely on HTTPS transport trust to the registry host. For provenance independent of the transport, pin the publisher's Ed25519 key as registrySigningPublicKey in ui.json: both ui:add and ui:update then verify the registry index against its detached signature before trusting anything, failing closed on a missing or invalid signature, reject a replayed older index, and bind every fetched item to the signed index's per-item content hash — a shipped guarantee, not a planned one.
• — License flags must match the source tier. An item under registry/open/ must declare "license": "open"; an item under registry/pro/ must declare "license": "pro".
• — Names are stable install slugs. The name field is the CLI key and must match the catalog slug. Namespaced components may use a nested source path whose leaf differs from that slug, such as ai-prompt in ui/ai/prompt.

Validate locally

Run the build in dry-run mode from the apps/docs-registry directory to catch manifest errors without writing any output files:

php artisan registry:build --dry-run

To also check that shared assets and per-item JS copies are in sync with their canonical sources (useful before opening a PR):

php artisan registry:mirror --check