Website · Documentation · GitHub · Changelog

Overview

@bpmnkit/docspack ships the BPMN Kit documentation the way an AI agent can actually use it: as an npm package whose version tracks the docs, indexed locally and searched offline.

An agent installs it, asks a question, and gets back the two or three passages that answer it — not a whole documentation site, and not whatever the model remembers about an older release.

It follows the docspack package format, so the upstream docspack CLI discovers and indexes it like any other vendor pack. The bundled bpmnkit-docs command does the same job with no extra tooling.

It also reads @bpmnkit/camunda-docspack — the Camunda 8 documentation in the same format. Install both and ask this one how to drive the library, that one what the engine does.

Markdown docs → chunks + manifest → BM25 index → three passages

Features

• Offline — ask, search and list read the filesystem only. No server, no network call, nothing resident between questions
• Version-locked — the installed package.json version wins over the manifest, so an agent reads the docs for the release it has
• Bounded answers — three chunks and 3,000 tokens by default, budgeted from the manifest before any content is read
• Real retrieval — BM25 over chunk text with Porter stemming, so authenticate finds a passage that only says authentication; tags and API identifiers weigh 3× prose
• docspack-compatible — .llms/manifest.json validates against https://docspack.dev/schema/v1.json
• Safe by construction — a manifest is untrusted input: chunk paths that escape .llms/ are refused, and community packages are labelled
• Zero runtime dependencies

Installation

npm install -D @bpmnkit/docspack

Quick Start

Give an agent one paragraph in AGENTS.md or CLAUDE.md — naming both packs, because an agent told only about the first will never think to ask the second:

Run `npx bpmnkit-docs ask "<question>"` for BPMN Kit documentation, and
`npx bpmnkit-docs ask "<question>" --pack @bpmnkit/camunda-docspack` for
Camunda 8 documentation — BPMN semantics, FEEL, engine behaviour, the REST API.
Both answer from the versions this project installed.

Then:

npx bpmnkit-docs ask "how do I deploy a process to Camunda 8"
npx bpmnkit-docs ask "what happens when no gateway condition is true" --pack @bpmnkit/camunda-docspack
npx bpmnkit-docs search "exclusive gateway"
npx bpmnkit-docs list

## @bpmnkit/[email protected]/getting-started.quick-start.step-3-deploy-and-run

# Quick Start — Step 3: Deploy and run
...

---
cost: 1,204 tokens, capped at 3,000

API Reference

// Discover and index every docs package installed under a directory
function discoverPacks(cwd?: string): Pack[]
function indexPacks(packs: readonly Pack[]): DocsIndex

// Rank chunks, or take the top ones that fit a token budget
function search(index: DocsIndex, query: string, options?: SearchOptions): SearchHit[]
function answer(
  index: DocsIndex,
  query: string,
  options?: AnswerOptions,
): { hits: SearchHit[]; tokens: number; maxTokens: number }

interface SearchOptions {
  limit?: number      // chunks to return. Default: 3
  packs?: readonly string[] // restrict to these package names
}

interface AnswerOptions extends SearchOptions {
  maxTokens?: number  // ceiling for an answer. Default: 3000
}

// Generate a .llms/ payload from a directory of Markdown
function buildPack(options: BuildOptions): BuildResult

// Read one package, validating it the way a consumer must
function loadPack(dir: string): Pack

CLI

| Command | Purpose | | --- | --- | | bpmnkit-docs ask <question> | Answer from the installed docs packages — the command to give an agent | | bpmnkit-docs search <query> | Rank matching chunks, for reading in a terminal | | bpmnkit-docs list | Show the docs packages found and their index state | | bpmnkit-docs build | Regenerate this package's .llms/ payload from the docs source |

Options: --limit <n>, --max-tokens <n>, --pack <name>, --cwd <dir>.

--pack narrows before the index is built, not after, so asking one pack a question does not pay for reading the others. A name that is not installed is an error listing what is, rather than an empty answer that would read as "the documentation does not cover this".

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process execution engine | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 22 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/camunda-docspack | Camunda 8 docs as an offline docspack package for AI agents | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/operate | Monitoring & operations frontend for Camunda clusters | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/connectors | Camunda 8 OOTB connector catalog and deterministic template application | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/proxy | Local AI bridge and Camunda API proxy server | | @bpmnkit/patterns | Domain process patterns for BPMNKit AIKit | | @bpmnkit/reebe-wasm | WebAssembly BPMN engine for browser simulation | | @bpmnkit/worker-client | Thin Zeebe REST client for standalone workers | | @bpmnkit/user-tasks | Embeddable user task widget for Camunda 8 | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data | | @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data | | @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |

License

MIT © BPMN Kit — made by u11g