Packaging a Knowledge Base

Overview

The pair package command creates a distributable ZIP from your Knowledge Base. It supports two layout modes that determine which files are included:

Source vs Target Layout

Source Layout

Packages from the source directory defined in each registry's source field in config.json. This is the canonical, pre-installation structure.

pair package --layout source

Use source layout when:

• You maintain a KB dataset and want to distribute the original files
• You want a clean package without installation-time transformations (prefix, flatten)
• You're building a CI/CD pipeline that packages from the dataset directly

Example: A KB with config.json registry skills.source: ".skills" packages from .skills/category/name/SKILL.md.

Target Layout

Packages from installed target directories — the files as they appear after pair install. This is the default.

pair package --layout target

Use target layout when:

• You want to package the KB as users see it after installation
• You need to include prefix/flatten transformations applied during install
• You're redistributing a customized KB from a project

Example: The same skills registry with flatten: true, prefix: "pair" packages from .claude/skills/pair-category-name/SKILL.md.

Packaging Walkthrough

1. Validate before packaging

# Validate with the same layout you'll package
pair kb validate --layout source
pair kb validate --layout target

2. Package

# Source layout — original dataset
pair package --layout source -o dist/my-kb-source.zip
 
# Target layout — installed structure (default)
pair package --layout target -o dist/my-kb-target.zip
 
# With metadata
pair package --layout source \
  --name "My KB" \
  --version 1.0.0 \
  --description "Team knowledge base"

3. Verify the package

# Inspect the ZIP contents
unzip -l dist/my-kb-source.zip
 
# Validate the packaged KB
pair kb validate dist/my-kb-source.zip

Organizational Packaging

For enterprise distribution, add organizational metadata:

pair package --layout source \
  --org \
  --org-name "Acme Corp" \
  --team "Platform" \
  --compliance "SOC2,ISO27001" \
  --distribution restricted

See Organization Customization for the full enterprise workflow.

Layout and config.json

The layout mode maps to the source and targets fields in your config.json registries:

{
  "asset_registries": {
    "skills": {
      "source": ".skills",
      "flatten": true,
      "prefix": "pair",
      "targets": [
        { "path": ".claude/skills", "mode": "canonical" },
        { "path": ".cursor/skills", "mode": "symlink" }
      ]
    }
  }
}

• --layout source reads from .skills/
• --layout target reads from .claude/skills/ (canonical target only — .cursor/skills/ is excluded because it's a symlink)