Skip to content

Registry & Marketplace

This document defines the Zakardo Registry — the distribution system for capability packs, plan packs, and custom catalog extensions. It covers the package format, publishing lifecycle, CLI integration, discovery, and marketplace features.

Prerequisites: This document assumes familiarity with Capability System (especially §14 Capability Packs), CLI and DX, Frontend Architecture (especially §4.3 Custom Catalogs), and PRD — Zakardo Cloud.


  1. npm-first distribution. All packs are valid npm packages. The Registry adds metadata, verification, and discovery — but packs install via pnpm add like any dependency.
  2. Typed contracts. Every pack declares typed schemas for its capabilities. Installing a pack gives the developer full IntelliSense, type-checked bindings, and build-time validation.
  3. Self-contained. A capability pack includes everything: definitions, implementations, A2UI catalog extensions, Anchored View templates, policy recommendations, test fixtures, and documentation.
  4. Trust by verification. The Registry runs automated quality checks on every published version: tests pass, schemas validate, documentation exists, bundle size within limits.
  5. Open + private. Public packs are discoverable by all. Organizations can publish private packs scoped to their team.

TypeDescriptionExample
Capability PackBundle of capabilities with schemas, implementations, A2UI components, and tests@zakardo-packs/stripe-payments
Plan PackPre-authored plans referencing capabilities from one or more capability packs@zakardo-packs/ecommerce-workflows
Catalog PackStandalone A2UI component catalog extensions@zakardo-packs/charts-catalog

Every pack includes a manifest at the package root:

{
"name": "@vendor/stripe-payments",
"version": "1.2.0",
"type": "capability",
"runtime_version": ">=1.0.0",
"description": "Stripe payment capabilities for Zakardo applications",
"author": {
"name": "Vendor Inc.",
"url": "https://vendor.com"
},
"capabilities": [
{
"name": "create_payment_intent",
"effect_class": "WRITE_EXTERNAL",
"boundary": "REMOTE",
"description": "Create a Stripe PaymentIntent"
},
{
"name": "list_charges",
"effect_class": "READ",
"boundary": "REMOTE",
"description": "List Stripe charges with filters"
},
{
"name": "refund_charge",
"effect_class": "WRITE_EXTERNAL",
"boundary": "REMOTE",
"description": "Refund a Stripe charge"
}
],
"a2ui_catalog": {
"name": "stripe-components",
"components": ["PaymentStatusCard", "ChargeTable", "RefundDialog"]
},
"anchored_views": ["views/charges-dashboard.json", "views/payment-detail.json"],
"policies": ["policies/refund-approval.json"],
"configuration": {
"required_env": ["STRIPE_API_KEY", "STRIPE_WEBHOOK_SECRET"],
"config_schema": {
"stripe_mode": { "type": "string", "enum": ["test", "live"], "default": "test" }
}
},
"test_fixtures": "fixtures/",
"documentation": "README.md"
}
@vendor/stripe-payments/
├── zakardo-pack.json # Pack manifest
├── README.md # Documentation
├── src/
│ ├── capabilities/
│ │ ├── create_payment_intent.ts
│ │ ├── list_charges.ts
│ │ ├── refund_charge.ts
│ │ └── index.ts
│ ├── catalog/
│ │ ├── PaymentStatusCard.ts
│ │ ├── PaymentStatusCardRenderer.tsx
│ │ ├── ChargeTable.ts
│ │ ├── ChargeTableRenderer.tsx
│ │ └── catalog.ts
│ └── index.ts
├── views/
│ ├── charges-dashboard.json # Anchored View definitions
│ └── payment-detail.json
├── policies/
│ └── refund-approval.json # Recommended policy
├── fixtures/
│ ├── seed.ts # Test fixture data
│ └── training-dataset.json # Training dataset for pack capabilities
├── package.json
└── tsconfig.json

Terminal window
# Validate pack before publishing
zakardo registry validate
# Publish to the public registry
zakardo registry publish
# Publish to a private (organization) scope
zakardo registry publish --scope @my-org
# Publish a specific version
zakardo registry publish --tag beta

Before publishing, the Registry runs automated checks:

CheckDescriptionRequired
Manifest validzakardo-pack.json schema validatesYes
Schemas validAll capability input/output schemas are valid JSON SchemaYes
Types compileTypeScript compilation succeedsYes
Tests passpnpm test passes (if tests exist)Yes
Effects declaredAll capabilities have effectClassYes
DocumentationREADME.md exists and is non-emptyYes
Bundle sizeTotal package < 5 MB (configurable)Yes
A2UI catalogAll components referenced in Anchored Views exist in the catalogYes
Runtime compatruntime_version range is valid semverYes
LicenseLicense field in package.jsonWarning
ChangelogCHANGELOG.md existsWarning
Developer → zakardo registry validate → All checks pass
→ zakardo registry publish
→ Package uploaded to npm
→ Registry indexes the pack:
- Extracts capability metadata
- Indexes for search
- Computes compatibility matrix
- Runs trust scoring
→ Pack available for installation

Packs follow semver. The Registry enforces compatibility:

ChangeVersion Bump
Add new capabilityMINOR
Add optional input fieldMINOR
Remove capabilityMAJOR
Change input schema (breaking)MAJOR
Change output schema (breaking)MAJOR
Bug fixPATCH
Add/change Anchored ViewMINOR
Change effect classMAJOR

Terminal window
# Install a public pack
zakardo registry install @vendor/stripe-payments
# Install a specific version
zakardo registry install @vendor/[email protected]
# Install a private pack
zakardo registry install @my-org/internal-crm --registry https://registry.my-org.com
# List installed packs
zakardo registry list
  1. npm install — adds the package to package.json devDependencies.
  2. Capability registration — updates packages/capabilities/src/packs.ts to register pack capabilities.
  3. Catalog merge — if the pack includes A2UI components, updates packages/catalog/src/catalog.ts to extend the catalog.
  4. Policy import — copies recommended policies to policies/ (with .recommended suffix; developer enables explicitly).
  5. Config prompt — prompts for required environment variables.
  6. Validate — runs zakardo validate to ensure the pack integrates correctly.

After installation, pack capabilities are available to the Planner and Execution Engine:

// packages/capabilities/src/packs.ts (auto-generated)
import stripePayments from '@vendor/stripe-payments';
import { registerPack } from '@zakardo/core';
registerPack(stripePayments, {
config: {
stripe_mode: process.env.STRIPE_MODE || 'test',
},
});

The Registry provides a searchable web interface at registry.zakardo.dev:

FeatureDescription
SearchFull-text search over pack names, descriptions, and capability names
CategoriesPayments, CRM, Email, Storage, Analytics, etc.
FiltersEffect class, boundary, runtime version, install count, rating
Pack detail pageREADME, capability list, schema preview, install command, version history
CompatibilityShows which Runtime versions a pack supports
Terminal window
# Search packs
zakardo registry search stripe
# Search with filters
zakardo registry search --category payments --effect WRITE_EXTERNAL
# Show pack details
zakardo registry info @vendor/stripe-payments

Each pack has a computed trust score based on:

FactorWeightDescription
Tests passing30%All tests pass on latest Runtime version
Documentation quality20%README completeness, API documentation
Version stability15%Frequency of major version bumps
Community adoption15%Install count, GitHub stars
Maintainer responsiveness10%Issue response time, release frequency
Security10%No known vulnerabilities, dependency audit

Teams on Zakardo Cloud Team or Enterprise tiers can publish private packs:

Terminal window
# Publish private
zakardo registry publish --scope @my-org --private
# Install from org scope
zakardo registry install @my-org/internal-crm

Enterprise customers can run a self-hosted registry:

Terminal window
# Configure CLI to use custom registry
zakardo config set registry https://registry.internal.corp.com
# All registry commands now target the self-hosted instance
zakardo registry publish
zakardo registry install @corp/capabilities

Plan packs contain pre-authored Plan IR files that reference capabilities from one or more capability packs:

{
"name": "@vendor/ecommerce-workflows",
"version": "1.0.0",
"type": "plan",
"runtime_version": ">=1.0.0",
"dependencies": ["@vendor/stripe-payments@>=1.0.0", "@vendor/email-capabilities@>=2.0.0"],
"plans": [
{
"name": "process-refund",
"description": "Full refund workflow: verify charge, process refund, send confirmation email",
"lifecycle_state": "promoted",
"trust_score": 0.95
},
{
"name": "subscription-upgrade",
"description": "Upgrade customer subscription with prorated billing",
"lifecycle_state": "promoted",
"trust_score": 0.88
}
]
}
Terminal window
zakardo registry install @vendor/ecommerce-workflows

Installation validates that all dependency capability packs are installed and compatible.


Standalone A2UI component catalogs that can be used across multiple capability packs:

{
"name": "@vendor/charts-catalog",
"version": "1.0.0",
"type": "catalog",
"runtime_version": ">=1.0.0",
"components": [
{ "name": "BarChart", "description": "Bar chart visualization" },
{ "name": "LineChart", "description": "Line chart with trend lines" },
{ "name": "PieChart", "description": "Pie chart with labels" },
{ "name": "Sparkline", "description": "Inline trend sparkline" }
]
}

Capability packs can reference catalog pack components in their Anchored Views:

{
"anchored_view": {
"catalog": "@vendor/charts-catalog",
"components": [
{
"id": "revenue",
"component": { "BarChart": { "data": { "dataPath": "/revenue_by_month" } } }
}
]
}
}

DecisionResolution
npm-firstPacks are npm packages. Registry adds metadata and discovery, not a custom package format.
Three pack typesCapability, plan, and catalog packs. Each has a distinct manifest schema but shares the publishing/discovery infrastructure.
Manifest filezakardo-pack.json at package root. Separate from package.json to avoid coupling.
Auto-registrationzakardo registry install auto-generates registration code. Developer does not manually wire packs.
Trust scoringComputed from tests, docs, stability, adoption, responsiveness, security. Not purely popularity.
Policy recommendationsPacks include recommended policies but do not auto-enable them. Developer explicitly enables.
Private registriesOrganization scopes on Zakardo Cloud. Self-hosted option for enterprise.

QuestionDeferred To
Revenue sharing model for paid capability packsBusiness planning
Automated security scanning pipeline for published packsSecurity Specification
How do packs handle peer dependency conflicts?Implementation detail (v1.0 planning)
Can packs include database migrations?Data Layer Specification (addendum)
How does the Registry handle pack deprecation and sunsetting?Implementation detail