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. Design Goals
Section titled “1. Design Goals”- npm-first distribution. All packs are valid npm packages. The Registry adds metadata, verification, and discovery — but packs install via
pnpm addlike any dependency. - 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.
- Self-contained. A capability pack includes everything: definitions, implementations, A2UI catalog extensions, Anchored View templates, policy recommendations, test fixtures, and documentation.
- Trust by verification. The Registry runs automated quality checks on every published version: tests pass, schemas validate, documentation exists, bundle size within limits.
- Open + private. Public packs are discoverable by all. Organizations can publish private packs scoped to their team.
2. Package Format
Section titled “2. Package Format”2.1 Pack Types
Section titled “2.1 Pack Types”| Type | Description | Example |
|---|---|---|
| Capability Pack | Bundle of capabilities with schemas, implementations, A2UI components, and tests | @zakardo-packs/stripe-payments |
| Plan Pack | Pre-authored plans referencing capabilities from one or more capability packs | @zakardo-packs/ecommerce-workflows |
| Catalog Pack | Standalone A2UI component catalog extensions | @zakardo-packs/charts-catalog |
2.2 Pack Manifest: zakardo-pack.json
Section titled “2.2 Pack Manifest: zakardo-pack.json”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"}2.3 Pack Directory Structure
Section titled “2.3 Pack Directory Structure”@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.json3. Publishing
Section titled “3. Publishing”3.1 CLI Publishing
Section titled “3.1 CLI Publishing”# Validate pack before publishingzakardo registry validate
# Publish to the public registryzakardo registry publish
# Publish to a private (organization) scopezakardo registry publish --scope @my-org
# Publish a specific versionzakardo registry publish --tag beta3.2 Pre-Publish Validation
Section titled “3.2 Pre-Publish Validation”Before publishing, the Registry runs automated checks:
| Check | Description | Required |
|---|---|---|
| Manifest valid | zakardo-pack.json schema validates | Yes |
| Schemas valid | All capability input/output schemas are valid JSON Schema | Yes |
| Types compile | TypeScript compilation succeeds | Yes |
| Tests pass | pnpm test passes (if tests exist) | Yes |
| Effects declared | All capabilities have effectClass | Yes |
| Documentation | README.md exists and is non-empty | Yes |
| Bundle size | Total package < 5 MB (configurable) | Yes |
| A2UI catalog | All components referenced in Anchored Views exist in the catalog | Yes |
| Runtime compat | runtime_version range is valid semver | Yes |
| License | License field in package.json | Warning |
| Changelog | CHANGELOG.md exists | Warning |
3.3 Publishing Lifecycle
Section titled “3.3 Publishing Lifecycle”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 installation3.4 Versioning Rules
Section titled “3.4 Versioning Rules”Packs follow semver. The Registry enforces compatibility:
| Change | Version Bump |
|---|---|
| Add new capability | MINOR |
| Add optional input field | MINOR |
| Remove capability | MAJOR |
| Change input schema (breaking) | MAJOR |
| Change output schema (breaking) | MAJOR |
| Bug fix | PATCH |
| Add/change Anchored View | MINOR |
| Change effect class | MAJOR |
4. Installation
Section titled “4. Installation”4.1 CLI Installation
Section titled “4.1 CLI Installation”# Install a public packzakardo registry install @vendor/stripe-payments
# Install a specific version
# Install a private packzakardo registry install @my-org/internal-crm --registry https://registry.my-org.com
# List installed packszakardo registry list4.2 What Installation Does
Section titled “4.2 What Installation Does”- npm install — adds the package to
package.jsondevDependencies. - Capability registration — updates
packages/capabilities/src/packs.tsto register pack capabilities. - Catalog merge — if the pack includes A2UI components, updates
packages/catalog/src/catalog.tsto extend the catalog. - Policy import — copies recommended policies to
policies/(with.recommendedsuffix; developer enables explicitly). - Config prompt — prompts for required environment variables.
- Validate — runs
zakardo validateto ensure the pack integrates correctly.
4.3 Pack Registration
Section titled “4.3 Pack Registration”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', },});5. Discovery
Section titled “5. Discovery”5.1 Web Interface
Section titled “5.1 Web Interface”The Registry provides a searchable web interface at registry.zakardo.dev:
| Feature | Description |
|---|---|
| Search | Full-text search over pack names, descriptions, and capability names |
| Categories | Payments, CRM, Email, Storage, Analytics, etc. |
| Filters | Effect class, boundary, runtime version, install count, rating |
| Pack detail page | README, capability list, schema preview, install command, version history |
| Compatibility | Shows which Runtime versions a pack supports |
5.2 CLI Search
Section titled “5.2 CLI Search”# Search packszakardo registry search stripe
# Search with filterszakardo registry search --category payments --effect WRITE_EXTERNAL
# Show pack detailszakardo registry info @vendor/stripe-payments5.3 Trust Scores
Section titled “5.3 Trust Scores”Each pack has a computed trust score based on:
| Factor | Weight | Description |
|---|---|---|
| Tests passing | 30% | All tests pass on latest Runtime version |
| Documentation quality | 20% | README completeness, API documentation |
| Version stability | 15% | Frequency of major version bumps |
| Community adoption | 15% | Install count, GitHub stars |
| Maintainer responsiveness | 10% | Issue response time, release frequency |
| Security | 10% | No known vulnerabilities, dependency audit |
6. Private Registries
Section titled “6. Private Registries”6.1 Organization Scopes
Section titled “6.1 Organization Scopes”Teams on Zakardo Cloud Team or Enterprise tiers can publish private packs:
# Publish privatezakardo registry publish --scope @my-org --private
# Install from org scopezakardo registry install @my-org/internal-crm6.2 Self-Hosted Registry
Section titled “6.2 Self-Hosted Registry”Enterprise customers can run a self-hosted registry:
# Configure CLI to use custom registryzakardo config set registry https://registry.internal.corp.com
# All registry commands now target the self-hosted instancezakardo registry publishzakardo registry install @corp/capabilities7. Plan Packs
Section titled “7. Plan Packs”7.1 Format
Section titled “7.1 Format”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 } ]}7.2 Installation
Section titled “7.2 Installation”zakardo registry install @vendor/ecommerce-workflowsInstallation validates that all dependency capability packs are installed and compatible.
8. Catalog Packs
Section titled “8. Catalog Packs”8.1 Format
Section titled “8.1 Format”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" } ]}8.2 Usage
Section titled “8.2 Usage”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" } } } } ] }}9. Summary of Decisions
Section titled “9. Summary of Decisions”| Decision | Resolution |
|---|---|
| npm-first | Packs are npm packages. Registry adds metadata and discovery, not a custom package format. |
| Three pack types | Capability, plan, and catalog packs. Each has a distinct manifest schema but shares the publishing/discovery infrastructure. |
| Manifest file | zakardo-pack.json at package root. Separate from package.json to avoid coupling. |
| Auto-registration | zakardo registry install auto-generates registration code. Developer does not manually wire packs. |
| Trust scoring | Computed from tests, docs, stability, adoption, responsiveness, security. Not purely popularity. |
| Policy recommendations | Packs include recommended policies but do not auto-enable them. Developer explicitly enables. |
| Private registries | Organization scopes on Zakardo Cloud. Self-hosted option for enterprise. |
10. Questions Deferred
Section titled “10. Questions Deferred”| Question | Deferred To |
|---|---|
| Revenue sharing model for paid capability packs | Business planning |
| Automated security scanning pipeline for published packs | Security 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 |