Skip to content

CLI & Developer Experience

This document defines Zakardo’s command-line interface, developer experience tooling, and the local development workflow. It covers the zakardo CLI binary, every command and subcommand, project scaffolding via create-zakardo, the development server, the build and validation pipeline, code generators, and Zakardo Studio integration.

Prerequisites: This document assumes familiarity with Full-Stack Framework, Data Layer, Capability System, Policy and Governance, Plan Library, Training and Validation, Execution Engine, and Runtime API.


  1. Zero-to-running in one command. npx create-zakardo scaffolds a complete project. zakardo dev starts everything. No manual wiring.
  2. Convention over configuration. The CLI discovers capabilities, policies, plans, and training datasets from well-known directories. Explicit registration is unnecessary.
  3. Fast feedback loops. Hot-reloading for capabilities, policies, and plans. Instant Vite HMR for frontend. No full restart unless config changes.
  4. Validate before shipping. zakardo validate catches schema mismatches, missing effect declarations, broken policy references, and invalid plan bindings — all before runtime.
  5. One CLI for everything. Developers never shell out to separate tools. zakardo migrate delegates to Prisma/Drizzle. zakardo training run runs datasets. zakardo trace inspect opens traces. One binary.
  6. Consistent across adapters. CLI commands behave the same regardless of the data adapter (Prisma vs. Drizzle). Adapter-specific behavior is transparent.
  7. Scriptable. Every command supports --json output for CI/CD pipelines. Exit codes are well-defined. No interactive prompts when --yes or CI=true.

The CLI is distributed as @zakardo/cli and installed as a devDependency. The binary is zakardo:

// package.json (root)
{
"devDependencies": {
"@zakardo/cli": "^1.0.0"
}
}

The CLI resolves the closest @zakardo/core in the project’s node_modules and uses it to access capabilities, config, and adapter interfaces. It does not embed its own runtime — it delegates to the locally installed packages.

zakardo <command> [subcommand] [options]
Commands:
dev Start the development server
build Build for production
validate Validate all Zakardo artifacts
migrate Run database migrations (via adapter)
seed Seed the database
training Run training datasets
trace Inspect and manage traces
plan Validate and manage plans
policy Manage policies
metadata Schema metadata operations
studio Launch Zakardo Studio
worker Start the execution worker
<type>:new Generate scaffolds (capability, route, policy, plan, service, component)
Global options:
--help Show help for command
--version Show CLI version
--json Output as JSON (for scripting)
--verbose Show debug-level output
--cwd <dir> Override working directory

Every command reads the project’s configuration from well-known locations:

config/zakardo.ts → Composed Zakardo config
config/data.ts → Data adapter config
config/auth.ts → Auth adapter config
config/execution.ts → Execution config
config/trace.ts → Trace config
env/schema.ts → Environment variable schema

The CLI validates the environment and config before executing any command. If environment variables are missing, the CLI fails fast with a clear message:

$ zakardo validate
✗ Missing environment variables:
DATABASE_URL (required by config/data.ts)
OPENAI_API_KEY (required by config/zakardo.ts)
Copy env/.env.example to .env and fill in the values.

A standalone package (create-zakardo) for bootstrapping new projects. Not part of the @zakardo/cli binary — invoked via npx:

$ npx create-zakardo my-crm

Interactive prompts:

PromptOptionsDefault
Database ORMPrisma, DrizzlePrisma
AuthenticationBetter Auth, NoneBetter Auth
Frontend frameworkReact (Vite), Vue (Vite), Angular, NoneReact
Include examples?Yes (customer CRUD), No (empty)Yes

Non-interactive mode (CI):

Terminal window
npx create-zakardo my-crm \
--orm prisma \
--auth better-auth \
--frontend react \
--examples yes
my-crm/
├── apps/
│ ├── api/ # Hono backend
│ │ ├── src/
│ │ │ ├── server.ts # Entry point (Foundation + Zakardo mount)
│ │ │ ├── foundation/ # Auth, billing, admin, API, webhooks, jobs
│ │ │ └── zakardo/ # mountZakardo() + runtime glue
│ │ └── tsconfig.json
│ └── web/ # Frontend (React/Vue/Angular)
│ ├── src/
│ └── tsconfig.json
├── packages/
│ ├── shared/ # Shared types and utilities
│ ├── db/ # Database schema + client
│ ├── core/ # Zakardo core types (re-export from @zakardo/core)
│ ├── capabilities/ # Business capability implementations
│ └── catalog/ # A2UI component catalog
├── config/ # Atomic config files
│ ├── zakardo.ts
│ ├── data.ts
│ ├── auth.ts
│ ├── execution.ts
│ ├── trace.ts
│ └── services.ts
├── env/
│ ├── schema.ts # Typed environment schema
│ └── .env.example
├── policies/ # Policy JSON files
├── plans/ # Plan IR JSON files
├── training/ # Training datasets
├── infra/
│ ├── docker-compose.yml # Local infrastructure (Postgres, Redis)
│ ├── Dockerfile.api
│ └── Dockerfile.web
├── turbo.json # Turborepo config
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.json # Root TypeScript config

After scaffolding, create-zakardo automatically:

  1. Runs pnpm install.
  2. Starts Docker Compose (Postgres + Redis).
  3. Runs the initial database migration (prisma migrate dev or drizzle-kit push).
  4. Applies Zakardo’s internal migrations (zakardo_* tables).
  5. Prints next steps:
    Done! Next steps:
    cd my-crm
    zakardo dev

The primary development command. Starts all components with hot-reloading:

$ zakardo dev
Starting infrastructure...
✓ Docker Compose (postgres, redis)
Starting backend...
✓ Hono server on http://localhost:3000
├── Foundation routes: /auth, /billing, /admin, /api/v1, /webhooks
└── Zakardo Runtime: /zakardo/*
✓ 14 capabilities loaded
✓ 3 policies loaded
✓ 2 plans loaded
Starting frontend...
✓ Vite dev server on http://localhost:5173
Starting Zakardo Studio...
✓ Studio on http://localhost:3000/zakardo/studio
Watching for changes...
├── packages/capabilities/** → auto-reload capabilities
├── policies/** → auto-reload policies
├── plans/** → auto-reload plans
├── config/** → restart runtime
└── packages/db/prisma/** → prompt migration
  1. Check prerequisites. Docker running? Node.js version ≥ 20? pnpm installed?
  2. Start infrastructure. docker compose up -d from infra/docker-compose.yml (if not already running).
  3. Run migrations. Check for pending database migrations. If found, prompt to apply.
  4. Validate environment. Load env/schema.ts. Fail fast if required variables are missing.
  5. Start backend. Launch Hono server with hot-reload (via tsx watch).
  6. Load Zakardo Runtime. Auto-discover and register capabilities, policies, plans. Extract schema metadata.
  7. Start frontend. Launch Vite dev server with HMR.
  8. Mount Studio. Serve @zakardo/studio at /zakardo/studio.
  9. Start watchers. File watchers on all Zakardo artifact directories.
ChangeActionRestart Required?
Capability source codeRe-register capability, hot-reloadNo
Policy JSON fileRe-load policy setNo
Plan JSON fileRe-load plan libraryNo
Config file (config/*)Restart Zakardo RuntimeYes (automatic)
Database schema (prisma/schema.prisma)Prompt developer to run migrationDeveloper action
Foundation route sourceStandard Hono/tsx hot-reloadNo
Frontend source codeVite HMRNo (instant)
Terminal window
zakardo dev api # Backend only (no frontend, no Studio)
zakardo dev web # Frontend only (expects backend running)
zakardo dev studio # Studio only (opens in browser)
zakardo dev --no-infra # Skip Docker Compose
zakardo dev --port 4000 # Custom backend port
ComponentDefault PortEnvironment Variable
Backend (Hono)3000PORT
Frontend (Vite)5173VITE_PORT
StudioSame as backend (/zakardo/studio)N/A
PostgreSQL5432PGPORT
Redis6379REDIS_PORT

Builds the application for production deployment:

$ zakardo build
Validating environment...
✓ env/schema.ts valid
Type-checking...
✓ packages/shared
✓ packages/db
✓ packages/core
✓ packages/capabilities
✓ packages/catalog
✓ apps/api
✓ apps/web
Validating Zakardo artifacts...
✓ 14 capabilities: schemas valid, effects declared
✓ 3 policies: syntax valid, referenced capabilities exist
✓ 2 plans: IR valid, capabilities available, policies satisfied
✓ 5 training datasets: intent payloads parse, expected responses valid
Building...
✓ apps/api → apps/api/dist/
✓ apps/web → apps/web/dist/
Build complete.

Build pipeline:

  1. Validate environment variables (production mode).
  2. Type-check all packages in dependency order (via Turborepo).
  3. Run zakardo validate (see §5.2).
  4. Bundle backend with tsup or esbuild.
  5. Bundle frontend with Vite production build.

Options:

Terminal window
zakardo build --skip-validate # Skip artifact validation
zakardo build --skip-types # Skip type-checking
zakardo build api # Build backend only
zakardo build web # Build frontend only

Validates all Zakardo artifacts without building. Runs as part of zakardo build but can be invoked standalone for fast feedback:

$ zakardo validate
Capabilities...
✓ 14 capabilities: schemas valid
✓ Effect classes declared
✓ Idempotency patterns verified for WRITE/DESTRUCTIVE capabilities
✓ Interaction Specs have valid response schemas
Policies...
✓ 3 policies: syntax valid
✓ Referenced capabilities and tags exist
✓ Gate approver roles exist in auth config
Plans...
✓ 2 plans: IR valid
✓ Capability references resolve
✓ Data bindings valid
✓ Policy compliance verified
Training datasets...
✓ 5 datasets: format valid
✓ Intent payloads parseable
✓ Expected responses match output schemas
Config...
✓ config/zakardo.ts composes successfully
✓ Data adapter connects (dry-run)
✓ Auth provider initializes
✓ LLM providers reachable
All artifacts valid. ✓
CategoryCheckSeverity
CapabilitiesInput/output schemas are valid JSON SchemaError
effectClass is declaredError
Effect class matches actual behavior (heuristic)Warning
WRITE/DESTRUCTIVE capabilities have idempotency patternsWarning
Interaction Spec response schema is validError
Anchored View config references valid catalog componentsWarning
PoliciesJSON syntax validError
Referenced capabilities existError
Referenced tags exist on at least one capabilityWarning
Gate approver roles exist in auth configWarning
No contradictory rules (DENY + ALLOW on same capability)Error
PlansPlan IR structure validError
All capability references resolveError
Data bindings reference valid step outputsError
Step order respects dependenciesError
Policy compliance satisfiedError
TrainingDataset format validError
Intent payloads are parseableError
Expected outputs match capability output schemasWarning
ConfigConfig composition succeedsError
Data adapter can connect (dry-run)Error
Auth provider initializesWarning
LLM providers are reachableWarning

Exit codes:

CodeMeaning
0All checks passed
1Errors found (at least one Error-severity check failed)
2Warnings only (all Error checks passed)

Selective validation:

Terminal window
zakardo validate capabilities # Capabilities only
zakardo validate policies # Policies only
zakardo validate plans # Plans only
zakardo validate training # Training datasets only
zakardo validate config # Configuration only

Validates a specific plan against the current capability set and policies. This is the CLI equivalent of what the Validator does at runtime (see Validator Specification):

$ zakardo plan validate plans/onboard-customer.json
Parsing Plan IR...
✓ Valid structure
Resolving capabilities...
Step 0: create_customer → ✓ found (v1.0.0)
Step 1: send_welcome_email → ✓ found (v1.0.0)
Step 2: create_subscription → ✓ found (v1.0.0)
Checking data bindings...
Step 1 input 'email' ← $steps[0].output.email → ✓ path valid
Step 2 input 'customer_id' ← $steps[0].output.id → ✓ path valid
Policy compliance...
Step 0 (create_customer, WRITE_INTERNAL): ✓ allowed
Step 1 (send_welcome_email, WRITE_EXTERNAL): ✓ gate required → gate defined
Step 2 (create_subscription, WRITE_EXTERNAL): ✓ gate required → gate defined
Plan valid. ✓

Delegates to the project’s data adapter’s migration tool. The CLI does not implement migration logic — it calls the adapter’s runMigrations() method:

Terminal window
# Generate + apply migration (development)
zakardo migrate dev
# Apply pending migrations (production)
zakardo migrate deploy
# Check migration status
zakardo migrate status
# Reset database (development only)
zakardo migrate reset

Adapter delegation:

CommandPrisma AdapterDrizzle Adapter
migrate devnpx prisma migrate devnpx drizzle-kit push
migrate deploynpx prisma migrate deploynpx drizzle-kit migrate
migrate statusnpx prisma migrate statusnpx drizzle-kit status
migrate resetnpx prisma migrate resetDrop + recreate via driver

After any successful migration, Zakardo automatically:

  1. Re-runs its own internal migrations (zakardo_* tables).
  2. Refreshes schema metadata.
  3. Re-validates capabilities against the new schema.

Seeds the database with initial or fixture data:

Terminal window
# Run the default seed script
zakardo seed
# Seed the fixtures database (for TRAINING mode)
zakardo seed --fixtures
# Seed from a specific script
zakardo seed --script seeds/demo-data.ts

Seed file convention:

seeds/default.ts
import { defineSeed } from '@zakardo/core';
import { PrismaClient } from '@my-app/db';
export default defineSeed(async (db: PrismaClient) => {
await db.customer.createMany({
data: [
{ name: 'Alice Johnson', email: '[email protected]', status: 'active' },
{ name: 'Bob Smith', email: '[email protected]', status: 'churned' },
],
});
});
OptionDescription
--fixturesTarget the fixtures database (FIXTURES_DB_URL). Used for training data.
--script <path>Run a specific seed file instead of seeds/default.ts.
--resetTruncate all business tables before seeding (does not touch zakardo_* tables).

Schema metadata operations:

Terminal window
# Refresh schema metadata from the database
zakardo metadata refresh
# Print extracted schema metadata
zakardo metadata show
# Print schema metadata as JSON
zakardo metadata show --json

metadata refresh is automatically called after zakardo migrate. The standalone command is useful for debugging or after manual schema changes.


Runs training datasets against the current capability set and Planner configuration:

Terminal window
# Run all training datasets
zakardo training run
# Run a specific dataset
zakardo training run customer-management
# Run with verbose output
zakardo training run --verbose

Output:

$ zakardo training run customer-management
Running: customer-management (12 cases)
Case 1: "Show me all active customers"
Classification: ✓ GENERATE (expected: GENERATE)
Plan generation: ✓ 1 step (list_customers)
Capability match: ✓ list_customers
Output match: ✓ matches expected schema
Case 2: "Create a new customer named Alice"
Classification: ✓ GENERATE (expected: GENERATE)
Plan generation: ✓ 1 step (create_customer)
Capability match: ✓ create_customer
Output match: ✓ matches expected schema
... (8 more cases)
Case 11: "What's your favorite color?"
Classification: ✓ CONVERSE (expected: CONVERSE)
Case 12: "Delete all customers" (should be blocked)
Policy block: ✓ DENY (bulk_delete_policy)
Results: 12/12 passed (100%)
Duration: 8.4s

List all available training datasets:

Terminal window
zakardo training list
Datasets:
customer-management 12 cases last run: 2026-02-10 20:30
order-processing 8 cases last run: 2026-02-09 14:15
email-workflows 5 cases never run

Training runs use the TRAINING execution mode. Capabilities execute against the fixtures database (seeded via zakardo seed --fixtures). No real data is touched.


Inspect execution traces from the CLI:

Terminal window
# List recent traces
zakardo trace list
# Inspect a specific trace
zakardo trace inspect trace_abc123
# Filter by status
zakardo trace list --status failed
# Show traces for a specific execution
zakardo trace list --execution exec_9d4b3f2a

Output:

$ zakardo trace inspect trace_abc123
Trace: trace_abc123
Execution: exec_9d4b3f2a
Intent: "Show me all churned customers and send them a recovery email"
Status: completed
Duration: 3.2s
Started: 2026-02-10T20:00:00Z
Completed: 2026-02-10T20:00:03Z
Timeline:
0ms INTENT_RECEIVED
120ms PLANNER_CLASSIFICATION → GENERATE (0.92)
450ms STEP_GENERATED → list_customers
680ms STEP_GENERATED → send_email_batch
900ms PLAN_VALIDATED
950ms GATE_TRIGGERED → requires approval (send_email_batch is WRITE_EXTERNAL)
1200ms GATE_RESOLVED → approved
1250ms STEP_STARTED → list_customers
1590ms STEP_COMPLETED → list_customers (340ms, 2 results)
1600ms STEP_STARTED → send_email_batch
2800ms STEP_COMPLETED → send_email_batch (1200ms, 2 sent)
2850ms OUTBOX_COMMITTED
3200ms EXECUTION_COMPLETED
Step Details:
[0] list_customers (READ)
Input: { filter: { status: "churned" } }
Output: { customers: [...], total: 2 }
DB Queries: 1 (SELECT on customers, 12ms)
[1] send_email_batch (WRITE_EXTERNAL)
Input: { recipients: [...], template_name: "recovery_promo" }
Output: { sent_count: 2, failed: [] }
Gate: approved by [email protected]

Export traces for offline analysis:

Terminal window
# Export as JSON
zakardo trace export trace_abc123 --format json > trace.json
# Export recent traces
zakardo trace export --last 10 --format json > recent-traces.json

Manage policy files:

Terminal window
# List loaded policies
zakardo policy list
# Create a new policy scaffold
zakardo policy create high-value-approval
# Enable/disable a policy
zakardo policy enable high-value-approval
zakardo policy disable high-value-approval
# Validate all policies
zakardo policy validate
# Test a policy against mock data
zakardo policy test high-value-approval --capability create_order --inputs '{"amount": 15000}'

Policy list output:

$ zakardo policy list
Policies:
Name Status Rules Capabilities
bulk-operations enabled 2 send_email_batch, delete_customers
high-value-approval enabled 1 create_order (amount > 10000)
destructive-gate enabled 1 * (effectClass: DESTRUCTIVE)

Test whether a policy would trigger for a given capability invocation:

$ zakardo policy test high-value-approval \
--capability create_order \
--inputs '{"amount": 15000}'
Policy: high-value-approval
Capability: create_order
Inputs: { amount: 15000 }
Result: GATE
Reason: Order amount ($15,000) exceeds high-value threshold ($10,000)
Gate type: approval
Approver roles: ["manager", "admin"]

The CLI provides generators for all Zakardo artifact types:

CommandCreatesLocation
zakardo capability:new <domain>/<name>Capability scaffoldpackages/capabilities/src/<domain>/<name>.ts
zakardo route:new <path>Foundation route scaffoldapps/api/src/foundation/<path>.ts
zakardo policy:new <name>Policy JSON scaffoldpolicies/<name>.json
zakardo plan:new <name>Plan IR scaffoldplans/<name>.json
zakardo service:new <name>Service provider scaffoldpackages/core/src/services/<name>.ts + config update
zakardo component:new <name>A2UI component scaffoldpackages/catalog/src/components/<name>.ts
$ zakardo capability:new customers/upgrade_plan
Created:
packages/capabilities/src/customers/upgrade_plan.ts
packages/capabilities/src/customers/upgrade_plan.test.ts
Updated:
packages/capabilities/src/customers/index.ts (added export)

Generated scaffold:

packages/capabilities/src/customers/upgrade_plan.ts
import { defineCapability } from '@zakardo/core';
import { z } from 'zod';
export default defineCapability({
name: 'upgrade_plan',
version: '1.0.0',
description: 'TODO: Describe what this capability does',
effectClass: 'WRITE_INTERNAL',
boundary: 'LOCAL',
tags: ['customers'],
inputSchema: z.object({
// TODO: Define input schema
}),
outputSchema: z.object({
// TODO: Define output schema
}),
execute: async (input, context) => {
// TODO: Implement capability logic
throw new Error('Not implemented');
},
});

All generators support common options:

Terminal window
zakardo capability:new customers/upgrade_plan --effect WRITE_EXTERNAL
zakardo capability:new customers/upgrade_plan --with-interaction
zakardo capability:new customers/upgrade_plan --with-anchored-view
zakardo policy:new high-value --from-template approval-gate
zakardo plan:new onboard-customer --steps 3

Each generator:

  1. Creates the file with a working scaffold (imports, types, stub implementation).
  2. Updates the relevant index file to export the new artifact.
  3. Runs the TypeScript compiler to verify no errors.

Starts the execution worker process for worker dispatch mode (see Execution Engine Specification §4.7):

Terminal window
# Start the worker
zakardo worker
# Start with custom concurrency
zakardo worker --concurrency 10
# Start with specific queue
zakardo worker --queue execution:advance

Output:

$ zakardo worker
Starting Zakardo Worker...
✓ Connected to Redis (localhost:6379)
✓ 14 capabilities loaded
✓ Queue: execution:advance
✓ Concurrency: 5
Worker ready. Waiting for jobs...

The worker process:

  1. Connects to Redis (reads config from config/execution.ts).
  2. Loads all capabilities and configuration (same as the API process).
  3. Consumes jobs from the BullMQ queue.
  4. Executes advanceExecution() for each job.
  5. Publishes events via RedisEventChannel.

Worker is only needed in worker dispatch mode. In in-process mode, execution runs on the API event loop and no worker is required.


Opens Zakardo Studio in the default browser. Studio is automatically mounted during zakardo dev, but this command can be used standalone:

Terminal window
# Open Studio (expects backend running)
zakardo studio
# Open Studio at custom URL
zakardo studio --url http://localhost:4000/zakardo/studio

Studio provides a GUI for many CLI commands. The CLI and Studio are complementary — not exclusive:

TaskCLIStudio
View capabilitieszakardo validate capabilitiesCapability Browser
Test an intentSDK or curlIntent Playground
Run a plan (simulated)zakardo training runPlan Tester
Inspect a tracezakardo trace inspectTrace Viewer
View policieszakardo policy listPolicy Inspector
Run trainingzakardo training runTraining Dashboard
View configcat config/*Config Viewer
Preview A2UIFrontend testingA2UI Preview

Recommended CI workflow:

.github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: pnpm install --frozen-lockfile
- run: pnpm exec zakardo validate --json
- run: pnpm exec zakardo build
- run: pnpm exec zakardo training run --json

Every command supports --json for machine-readable output:

Terminal window
$ zakardo validate --json
{
"status": "pass",
"categories": {
"capabilities": { "checked": 14, "errors": 0, "warnings": 0 },
"policies": { "checked": 3, "errors": 0, "warnings": 0 },
"plans": { "checked": 2, "errors": 0, "warnings": 0 },
"training": { "checked": 5, "errors": 0, "warnings": 0 },
"config": { "checked": 1, "errors": 0, "warnings": 0 }
},
"total_errors": 0,
"total_warnings": 0
}

The CLI automatically adjusts behavior when running in CI:

  • No interactive prompts. All prompts auto-accept defaults (same as --yes).
  • No color output when stdout is not a TTY (unless --color is specified).
  • Exit codes are strict — warnings in CI produce exit code 2 (configurable via --strict).

The composed configuration file that merges all individual configs:

import { defineZakardoConfig } from '@zakardo/core';
import { data } from './data';
import { auth } from './auth';
import { execution } from './execution';
import { trace } from './trace';
import { services } from './services';
export default defineZakardoConfig({
data,
auth,
execution,
trace,
services,
planner: {
provider: 'openai',
model: 'gpt-4o',
temperature: 0.1,
maxRetries: 3,
},
studio: {
enabled: process.env.NODE_ENV !== 'production',
},
});

The CLI validates config at startup and on every config change:

ValidationWhenSeverity
All define*Config calls produce valid objectsStartupError
Data adapter connects successfullyzakardo dev, zakardo validateError
LLM providers are reachablezakardo validateWarning
Auth provider initializeszakardo validateWarning
Execution dispatch mode matches infrastructurezakardo validateWarning

CLI errors are designed to be:

  1. Descriptive. State what went wrong.
  2. Actionable. Tell the user what to do about it.
  3. Contextual. Include file paths, line numbers, and relevant values.

Example:

$ zakardo validate
✗ Capability "list_customers" (packages/capabilities/src/customers/list_customers.ts)
Error: Input schema references non-existent type "CustomerFilter"
Fix: Define CustomerFilter in packages/shared/src/types.ts or update the schema
✗ Policy "high-value-approval" (policies/high-value-approval.json)
Error: References capability "create_invoice" which is not registered
Registered capabilities: create_customer, list_customers, send_email, ...
✗ Plan "onboard-customer" (plans/onboard-customer.json)
Error: Step 2 data binding "$steps[1].output.invoice_id" — step 1 output schema does not contain "invoice_id"
Step 1 output schema: { id: string, name: string, email: string }
Validation failed: 3 errors, 0 warnings
CodeMeaning
ZAKARDO_E001Missing environment variable
ZAKARDO_E002Config composition failure
ZAKARDO_E003Data adapter connection failure
ZAKARDO_E004Capability schema validation failure
ZAKARDO_E005Policy syntax error
ZAKARDO_E006Plan IR validation failure
ZAKARDO_E007Unresolved capability reference
ZAKARDO_E008Invalid data binding
ZAKARDO_E009Training dataset format error
ZAKARDO_E010Migration pending

DecisionResolution
Single CLI binaryOne zakardo binary for all operations. No separate tools for migration, validation, or training.
Adapter delegation for migrationszakardo migrate delegates to Prisma Migrate or Drizzle Kit. CLI never generates SQL itself.
Convention-based discoveryCapabilities from packages/capabilities/, policies from policies/, plans from plans/, training from training/. No manual registration.
Validate-before-buildzakardo build runs full validation before building. Catches errors at dev time, not runtime.
JSON output for CIEvery command supports --json for scriptable pipelines. Exit codes are well-defined.
create-zakardo is standaloneProject scaffolding is a separate npx package, not a subcommand of the CLI. Avoids chicken-and-egg dependency.
Studio is development-onlyNot included in production builds. Mounted alongside the dev server.
Worker as CLI commandzakardo worker starts the execution worker. Same binary, same config. No separate installation.
Generators update index filesScaffolding is not just file creation — generators also wire up exports and verify TypeScript compilation.

QuestionDeferred To
What is the exact A2UI component scaffold template?Frontend Architecture Specification
How does Studio authenticate in development?Security Specification
What is the deployment pipeline for Zakardo Cloud managed instances?PRD — Zakardo Cloud
How does the CLI handle monorepo vs. single-package projects?Future planning (v2 scope)
What is the plugin system for custom CLI commands?Registry and Marketplace Specification