@vorelai/pack-sdk

The Vorel vertical-pack SDK — validator API, hand-rolled TypeScript types, sidecar loaders, cross-pack lint, persona registry, and the create-pack scaffolding CLI for authoring per-vertical configuration packs.

What it is

A vertical pack is a self-contained bundle of per-industry configuration (slots, attributes, FAQ seed, CRM field-map suggestions, resolution rules, persona, eval rubric) that the Vorel agent runtime composes at request time. The frozen pack JSON Schema lives in the Vorel monorepo at config/verticals/_schema.json and is governed by CONTRACTS § 7.

This SDK packages the developer ergonomics around that schema for partners authoring third-party packs outside the monorepo:

• validateVerticalPack(json) — ajv-backed validator returning a discriminated union { ok: true; value } | { ok: false; errors }.
• parseVerticalPack(json) — throwing variant for CLI / script use.
• Type definitions — VerticalPack, ResolutionRule, AttributeSpec, SlotSpec, FAQSeed, CRMFieldMapSuggestions, etc., mirroring the JSON Schema (hand-rolled — see ADR 0010 § 3).
• Sidecar loaders — loadFAQSeed, loadCRMFieldMapSuggestions.
• Sidecar validators — validateFAQSeed, validateCRMFieldMap, validateRubric, validatePersonaRegistry. Schemas locked at v1 per ADR 0011.
• create-pack CLI — scaffolds a canonical pack JSON + sidecars + a stub eval rubric that all pass the validator immediately.
• pack-sdk-lint CLI — 8 cross-pack consistency rules (slot-key uniqueness, persona-name collisions, CRM-driver coverage, rubric-criterion duplication, FAQ-locale parity, etc.). Programmatic entry: lintPacks().

Install

npm install @vorelai/pack-sdk
# or
pnpm add @vorelai/pack-sdk
# or
yarn add @vorelai/pack-sdk

Pin a specific minor while the SDK is on the 0.x series — breaking changes are allowed between minors until 1.0 is cut:

{
  "dependencies": {
    "@vorelai/pack-sdk": "0.1.x",
  },
}

Requires Node 20 or 22. Pure ESM — "type": "module" in your package.json, or use the appropriate dynamic import shim in a CJS project.

Quickstart (partner-authoring flow)

# 1. Scaffold a new pack
npx create-pack my_vertical

# This writes:
#   config/verticals/my_vertical.json
#   config/verticals/my_vertical/faq-seed.json
#   config/verticals/my_vertical/crm-field-map-suggestions.json
#   config/eval/verticals/my_vertical.json

# 2. Edit my_vertical.json — replace TODO: placeholders with real values

# 3. Validate locally before submitting a PR
npx pack-sdk-lint

Authoring guidance, attribute-typing rules, resolution-rule patterns, bilingual FAQ-seed conventions, and the partner contribution agreement are documented in the Vorel handoff guide:

→ Pack authoring guide

Programmatic API

import { validateVerticalPack, parseVerticalPack, loadFAQSeed, lintPacks } from '@vorelai/pack-sdk';
import { readFileSync } from 'node:fs';

const raw = JSON.parse(readFileSync('config/verticals/clinic.json', 'utf8'));

const result = validateVerticalPack(raw);
if (!result.ok) {
  for (const err of result.errors) {
    console.error(`${err.path}: ${err.message}`);
  }
  process.exit(1);
}

const pack = result.value;
console.log(`Loaded pack ${pack.slug} (${pack.label})`);

const faq = loadFAQSeed('config/verticals', pack.slug, 'en');
if (faq) {
  console.log(`${faq.entries.length} FAQ entries`);
}

// Cross-pack lint
const lintResults = lintPacks([pack]);
for (const finding of lintResults) {
  console.log(`[${finding.severity}] ${finding.rule}: ${finding.message}`);
}

CLIs

create-pack

npx create-pack <slug> [--dry-run] [--force] [--bilingual]

| Flag | Effect | | ------------- | --------------------------------------------------------------------------------------------------- | | --dry-run | Print the paths that would be created. Writes nothing. Exit 0 = clear / 1 = collision. | | --force | Allow overwrite of an existing pack. SDK developers iterating on the template use this. | | --bilingual | Also scaffold faq-seed.ar.json mirroring the English file with // TODO_AR placeholders per row. |

Exit codes:

| Code | Meaning | | ---- | ------------------------------------------------ | | 0 | Success | | 1 | Dry-run failure (would collide) | | 2 | Invalid slug shape — must match /^[a-z0-9_]+$/ | | 3 | Slug collision without --force | | 4 | config/verticals/ not found from cwd upward | | 5 | File write failure (OS error reported) |

pack-sdk-lint

npx pack-sdk-lint [--packs-dir <path>] [--format text|json]

Runs 8 cross-pack consistency rules over every pack discovered under config/verticals/. Defaults to walking up from cwd looking for the config/verticals/ directory. JSON output is wired so the marketplace UI (Q4) can consume it for "Pack quality score" badges.

License

UNLICENSED — see LICENSE. The package is published to npm as a convenience for partners covered by a separate written contribution agreement. Until Vorel formally relaxes the license, partners cannot use the SDK outside that agreement.

See also

• Pack authoring guide (handoff/docs/pack-authoring.md)
• Workstream brief WS-J
• ADR 0010 — Pack SDK packaging + API shape
• ADR 0011 — Sidecar schema lock + extension policy
• CHANGELOG
• Issue tracker