Knowledge Pack Documentation

Installation

macOS & Linux

curl -fsSL https://kpack.dev/install.sh | sh

Windows (PowerShell)

irm https://kpack.dev/install.ps1 | iex

From Source

# Requires Rust 1.70+
git clone https://github.com/andrescastane/knowledge-pack
cd knowledge-pack/cli
cargo install --path .

Verify Installation

kp --version
# kp 0.5.2

Update

kp update

Quick Start

Create your first Knowledge Pack in under a minute:

# Create a new pack
kp init my-knowledge

# Navigate to it
cd my-knowledge

# Validate structure
kp validate

# Generate bundle for AI
kp bundle -o context.md

That's it! Your context.md file contains your entire knowledge pack in a format optimized for AI context windows.

Pack Structure

A Knowledge Pack has a simple, flat structure:

my-pack/
├── manifest.yaml      # Pack metadata and configuration
├── START_HERE.md      # AI entry point (read this first)
├── README.md          # Human-readable overview
├── index/
│   ├── topics.yaml    # Topic index for navigation
│   ├── glossary.yaml  # Term definitions
│   └── relations.yaml # Document relationships
└── docs/
    ├── getting-started.md
    ├── architecture.md
    └── api-reference.md

Key Files

• manifest.yaml — The pack's identity card. Contains name, version, configuration.
• START_HERE.md — The AI always reads this first. Provides navigation hints.
• index/ — Semantic indices that help AI understand relationships.
• docs/ — Your actual documentation files.

Manifest

The manifest.yaml is the configuration file for your pack:

id: my-org-knowledge
name: My Organization Knowledge
version: 1.0.0
description: Internal knowledge base for engineering team

config:
  language: en           # Primary language: en, es
  validation: strict    # strict or relaxed
  ai_editable: false    # Can AI modify this pack?

tags:
  - engineering
  - internal
  - onboarding

entry_points:
  human: README.md
  ai: START_HERE.md

Document Frontmatter

Every markdown document should have YAML frontmatter:

---
id: authentication-guide
title: Authentication Guide
type: guide              # guide, reference, concept, tutorial
description: How to implement authentication in our system

topics:
  - authentication
  - security

confidence: authoritative  # authoritative, reviewed, draft
editable_by_ai: false

dependencies:
  - getting-started
related:
  - api-reference
---

# Authentication Guide

Your content here...

Confidence Levels

• authoritative — Official, verified documentation. AI should trust this.
• reviewed — Has been reviewed but may need updates.
• draft — Work in progress. AI should treat with caution.

Document Types

• guide — How-to instructions for completing a task.
• reference — Technical reference (API, config options).
• concept — Explains ideas and architecture.
• tutorial — Step-by-step learning path.

Indices

Indices help AI navigate your knowledge efficiently. They're like a semantic map of your documentation.

topics.yaml

Maps topics to relevant documents:

topics:
  authentication:
    description: User authentication and authorization
    primary_docs:
      - docs/authentication-guide.md
    related_docs:
      - docs/api-reference.md
  
  deployment:
    description: How to deploy our services
    primary_docs:
      - docs/deployment.md

glossary.yaml

Defines terms specific to your organization:

terms:
  ACME:
    definition: Our internal deployment platform
    see_also:
      - deployment
  
  Golden Path:
    definition: The recommended way to build services

CLI Reference

kp init

Create a new Knowledge Pack with interactive setup.

# Interactive mode (prompts for language and template)
kp init

# Create in specific directory
kp init my-project

# Create with Spanish templates
kp init -l es

# Skip prompts, use defaults
kp init --yes

# Minimal template (fewer files)
kp init -t minimal

kp validate

Validate pack structure and check for errors.

# Validate current directory
kp validate

# Strict mode (warnings become errors)
kp validate --strict

# JSON output for CI pipelines
kp validate -f json

kp bundle

Generate a single file containing your entire pack, optimized for AI context windows. This is the primary way to feed your knowledge to an AI.

# Print to stdout (pipe to clipboard)
kp bundle | pbcopy

# Save to file
kp bundle -o context.md

# Include full document contents
kp bundle --raw -o full-context.md

# XML format (some AIs prefer this)
kp bundle -f xml -o context.xml

# Limit token count
kp bundle --max-tokens 50000 -o context.md

kp context

Get relevant documents for a specific topic.

# Find docs about authentication
kp context authentication

# Include related topics (depth)
kp context api --depth 2

# JSON output
kp context deployment -f json

# Include document contents
kp context auth --include-content

kp search

Full-text search across all documents in your pack.

# Search for a term
kp search "authentication"

# Search with context lines
kp search "JWT" --context 3

# JSON output
kp search "deploy" -f json

kp serve

Start a local web server to browse your documentation with a clean UI.

# Start server on default port
kp serve

# Custom port and auto-open browser
kp serve --port 8080 --open

kp stats

Show statistics about your pack.

kp stats

# Output:
# Documents: 12
# Topics: 8
# Glossary terms: 15
# Total words: 24,532
# Estimated tokens: ~6,100

kp lint

Check documents against style guidelines and writing profile rules.

# Lint all documents
kp lint

# Auto-fix simple issues
kp lint --fix

# Show only errors (no warnings)
kp lint --errors-only

kp export

Export pack to various formats.

# Export as JSON
kp export json -o pack.json

# Single markdown file
kp export single-md -o docs.md

# Static HTML site
kp export html -o site/

kp describe

Generate an AI-optimized description of your pack.

# Human-readable description
kp describe

# JSON output
kp describe -f json

# Short summary only
kp describe -s

kp transfer

Transfer and merge external documentation into your pack.

# Detect docs to transfer
kp transfer . -k ./kpack --agent detect

# Preview transfer plan
kp transfer . -k ./kpack --auto --dry-run

# Execute transfer
kp transfer . -k ./kpack --auto

kp profile

View and manage the writing profile that guides AI content generation.

# Show current profile
kp profile

# Generate AI system prompt from profile
kp profile --prompt

# JSON output for integrations
kp profile --prompt -f json

# Edit profile interactively
kp profile --edit

kp upgrade

Upgrade an existing Knowledge Pack to the latest structure format.

# Preview changes
kp upgrade --dry-run

# Apply upgrade
kp upgrade

kp mcp

Machine-consumable commands for AI agent integration.

# Get compact index for AI
kp mcp index --compact

# Read a specific document
kp mcp read docs/api.md

# List all documents
kp mcp list

kp ai

AI-powered analysis commands. Requires an API key set via environment variable.

# Set API key
export OPENAI_API_KEY=sk-...

# Find documentation gaps
kp ai suggest --gaps

# Summarize a document
kp ai summarize docs/architecture.md

# Review document quality
kp ai review docs/api.md

AI Integration

The main use case for Knowledge Pack is providing context to AI assistants. Here's how to integrate it into your workflow:

1. Generate the bundle

kp bundle --raw -o .ai/context.md

2. Add to your AI prompt

Include the bundle at the start of your conversation:

# In your system prompt or initial message:
"Here is our organizational knowledge base:

[Contents of context.md]

Please use this context when answering questions about our systems."

3. Use with Claude Projects / GPT Custom Instructions

Upload your bundle file to Claude Projects or include in ChatGPT's custom instructions for persistent context across conversations.

4. IDE Integration

Clone your knowledge-pack repo alongside your project. AI assistants in your IDE (Copilot, Cursor, etc.) will automatically index it.

workspace/
├── my-project/        # Your code
└── org-knowledge/     # Your Knowledge Pack

Best Practices