# Knowledge Pack (kpack)

> AI-native documentation format for institutional knowledge.

Knowledge Pack is a structured documentation format designed to be consumed by AI systems. It organizes technical knowledge in a way that's easy for LLMs to understand and retrieve.

## What is a Knowledge Pack?

A Knowledge Pack is a Git repository containing:
- `manifest.yaml` - Pack identity, metadata, writing profile, and configuration
- `START_HERE.md` - AI entry point (agents read this first)
- `README.md` - Human entry point
- `docs/` - Markdown documents with YAML frontmatter
- `index/topics.yaml` - Topic taxonomy and relations
- `index/glossary.yaml` - Term definitions
- `index/relations.yaml` - Document relationships

## Installation

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

Or from source (Rust 1.70+):
```bash
git clone https://github.com/andrescastane/knowledge-pack.git
cd knowledge-pack/cli
cargo install --path .
```

## CLI Commands

### kp init
Create a new Knowledge Pack.
```
kp init [NAME] [-t template] [-l language] [--no-git] [-f] [--yes]
```
- `NAME`: Directory name (default: current directory)
- `-t, --template`: minimal or standard (default: standard)
- `-l, --language`: en or es (default: en)
- `--no-git`: Skip Git initialization
- `-f, --force`: Overwrite existing directory
- `--yes`: Non-interactive mode

### kp validate
Validate pack structure and schemas.
```
kp validate [PATH] [-s] [-f format] [--fix]
```
- `-s, --strict`: Treat warnings as errors
- `-f, --format`: text, json, github (default: text)
- `--fix`: Auto-fix simple issues

### kp bundle
Generate single file for AI context windows.
```
kp bundle [PATH] [-o output] [--max-tokens N] [--raw] [-f format]
```
- `-o, --output`: Output file (stdout if omitted)
- `--max-tokens`: Token limit for truncation
- `--raw`: Include full content
- `-f, --format`: markdown or xml (default: markdown)

### kp context
Get context for a specific topic.
```
kp context <TOPIC> [-p path] [-d depth] [-m max] [-f format] [--area AREA] [--include-content]
```
- `<TOPIC>`: Topic to search for
- `-d, --depth`: Relation depth (default: 1)
- `-m, --max-files`: Max files (default: 10)
- `-f, --format`: list, json, prompt (default: list)
- `--area`: Filter by area/namespace
- `--include-content`: Include file contents

### kp stats
Show pack statistics.
```
kp stats [PATH] [-f format] [--area AREA]
```
- `--area`: Filter stats by area

### kp export
Export pack in various formats.
```
kp export <FORMAT> [-o output]
```
Formats: json, yaml, single-md, html

### kp index
Generate or update indices.
```
kp index [--only type] [--dry-run] [-f]
```

### kp lint
Check style and formatting.
```
kp lint [--fix] [--errors-only]
```

### kp describe
Get AI-optimized pack description.
```
kp describe [-f format] [-s]
```

### kp search
Full-text search across all documents.
```
kp search <QUERY> [-p path] [-f format] [--context N]
```
- `<QUERY>`: Search term
- `--context`: Lines of context around matches
- `-f, --format`: text or json

### kp serve
Start local documentation server with web UI.
```
kp serve [--port PORT] [--open]
```
- `--port`: Server port (default: 3000)
- `--open`: Open browser automatically

### kp transfer
Transfer and merge external documentation into a pack.
```
kp transfer <SOURCE> -k <KPACK_PATH> [--auto] [--dry-run] [--agent detect|structure] [--json]
```
- `--auto`: Automatic transfer
- `--dry-run`: Preview without changes
- `--agent detect`: Detect transferable files
- `--agent structure`: Analyze existing structure

### kp profile
View and manage writing profile.
```
kp profile [--prompt] [-f format] [--edit]
```
- `--prompt`: Generate AI system prompt from profile
- `--edit`: Interactive profile editor

### kp upgrade
Upgrade pack to latest structure format.
```
kp upgrade [--dry-run]
```

### kp mcp
Machine-consumable commands for AI agents.
```
kp mcp <SUBCOMMAND>
```
- `kp mcp index [--compact]` - Compact index for AI
- `kp mcp read <FILE>` - Read a specific document
- `kp mcp list` - List all documents

### kp doctor
Diagnose pack health issues.
```
kp doctor [PATH]
```

### kp update
Update kp CLI to latest version.
```
kp update [--check]
```

### kp completions
Generate shell completions.
```
kp completions <SHELL>
```
Shells: bash, zsh, fish, powershell, elvish

### kp ai (EXPERIMENTAL)
AI-powered analysis. Requires OPENAI_API_KEY or ANTHROPIC_API_KEY.

Subcommands:
- `kp ai suggest [--gaps]` - Find documentation gaps
- `kp ai summarize <FILE>` - Generate summaries
- `kp ai review <FILE>` - Review quality

## Pack Structure

### Standalone Mode
```
my-knowledge/
├── manifest.yaml          # Pack identity and configuration
├── START_HERE.md          # AI entry point
├── README.md              # Human entry point
├── index/
│   ├── topics.yaml        # Topic index
│   ├── glossary.yaml      # Term definitions
│   └── relations.yaml     # Document relations
└── docs/
    ├── overview/          # Introduction, getting started
    ├── guides/            # Step-by-step guides
    ├── reference/         # API docs, CLI reference
    ├── architecture/      # Design decisions, ADRs
    └── concepts/          # Core concepts explained
```

### Embedded Mode (inside existing project)
```
my-project/
├── src/                   # Project code
├── package.json           # Project config
└── docs/                  # ← EMBEDDED KPACK
    ├── manifest.yaml
    ├── START_HERE.md
    ├── index/
    │   ├── topics.yaml
    │   ├── glossary.yaml
    │   └── relations.yaml
    ├── overview/
    ├── guides/
    ├── reference/
    └── architecture/
```

Set `config.mode: embedded` in manifest.yaml for embedded packs.

## manifest.yaml Schema

```yaml
id: my-pack
name: My Knowledge Pack
version: 1.0.0
description: Pack description

config:
  language: en             # en or es
  validation: strict       # strict or relaxed
  ai_editable: true
  mode: standalone         # standalone or embedded

writing:
  purpose: technical-docs  # technical-docs, creative-fiction, api-spec, etc.
  tone: professional       # formal, casual, narrative, academic, etc.
  style:
    preset: markdown-docs
    avoid: ["buzzwords"]
    prefer: ["active voice"]

domains: [backend, security]
audience: [developer, ai-agent]
tags: [engineering]

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

## Document Frontmatter

```yaml
---
id: auth-guide
title: Authentication Guide
type: guide                # guide, reference, concept, tutorial
topics:
  - authentication
  - security
confidence: stable         # authoritative, stable, draft
editable_by_ai: false
last_updated: "2026-01-23"
---
```

## topics.yaml Schema

```yaml
version: "1.0"

topics:
  authentication:
    description: User authentication patterns
    priority: high
    keywords: [auth, login, jwt, oauth]
    files:
      - path: docs/guides/auth-guide.md
        role: primary
      - path: docs/reference/jwt.md
        role: detail

  deployment:
    description: Deployment processes and patterns
    priority: medium
    keywords: [deploy, docker, kubernetes, ci-cd]
    files:
      - path: docs/guides/deployment.md
        role: primary
```

## Areas and Large Projects

Knowledge Pack supports organizing large projects with area-based directories:

### Example Structure:
```
org-knowledge/
├── manifest.yaml
├── START_HERE.md
├── docs/
│   ├── overview/         ← Introduction
│   ├── guides/           ← Step-by-step guides
│   ├── reference/        ← API and CLI reference
│   ├── architecture/     ← Design decisions
│   └── concepts/         ← Core concepts
└── index/
    ├── topics.yaml       ← Organized by areas
    ├── glossary.yaml     ← Shared terms
    └── relations.yaml    ← Cross-area relations
```

### Commands with Area Filter:
```bash
kp context authentication --area backend
kp stats --area frontend
kp bundle --area api -o api-context.md
```

Benefits:
- Single source of truth
- Unified search across all areas
- Cross-area relationships visible
- Shared glossary
- Complete bundle for AI

## glossary.yaml Schema

```yaml
terms:
  - term: JWT
    definition: JSON Web Token for authentication
    see_also: [OAuth, Bearer Token]
  - term: API Key
    definition: Secret key for API authentication
```

## relations.yaml Schema

```yaml
relations:
  - source: docs/architecture.md
    target: docs/api/reference.md
    type: references
  - source: docs/getting-started.md
    target: docs/architecture.md
    type: prerequisite
```

## Best Practices

1. Write documents with AI consumption in mind
2. Use clear, specific summaries in frontmatter
3. Define all acronyms in glossary.yaml
4. Use topics.yaml for semantic organization
5. Keep documents focused on single topics
6. Link related documents explicitly
7. Use `kp validate` before committing
8. Use `kp bundle` to feed context to AI

## Links

- Website: https://kpack.dev
- Documentation: https://kpack.dev/docs/
- CLI Reference: https://kpack.dev/docs/cli-reference/
- GitHub: https://github.com/andrescastane/knowledge-pack
- Install Script: https://kpack.dev/install.sh