---
name: KB Setup
slug: kb-setup
category: Automation
description: KB Setup brings up a local markdown knowledge base for a project. Use it to initialize or configure sources, index docs, and verify search works with a smoke query.
github: "https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/develop/packages/kb/skill/kb-setup"
language: TypeScript
stars: 267
forks: 38
install: "npx degit https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/develop/packages/kb/skill/kb-setup ~/.claude/skills/kb-setup"
installs_to: ~/.claude/skills/kb-setup
source_path: packages/kb/skill/kb-setup/SKILL.md
collection_size: 5
category_size: 1525
collection_url: "https://dirskills.com/collections/BlackBeltTechnology/pi-agent-dashboard"
added: 2026-09-01T14:36:04.111Z
last_synced: 2026-09-01T14:36:04.111Z
canonical_url: "https://dirskills.com/skills/kb-setup"
---

# KB Setup

KB Setup brings up a local markdown knowledge base for a project. Use it to initialize or configure sources, index docs, and verify search works with a smoke query.

**Install:**

```bash
npx degit https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/develop/packages/kb/skill/kb-setup ~/.claude/skills/kb-setup
```

## README

# kb-setup — bring up the project knowledge base

`@blackbelt-technology/pi-dashboard-kb` builds a zero-token, local SQLite/FTS5
index over this project's markdown so `kb-search` can retrieve before answering.
This SKILL does the one-time bring-up. Retrieval is **pull** (the agent calls
`kb`); nothing is auto-injected.

## When to Use

- User asks to set up / init / configure the knowledge base.
- No `.pi/dashboard/knowledge_base.json` exists yet and the project has docs.
- User wants to add a doc source (local dir, npm package docs, git handbook).

## Procedure

1. **Detect existing config.** Check `.pi/dashboard/knowledge_base.json`
   (project) and `~/.pi/dashboard/knowledge_base.json` (global). Run
   `kb config` to see the resolved layering. If a project config already exists
   and is healthy, skip to step 5 (smoke search) unless the user wants changes.
2. **Choose scope + sources.** Ask (if unclear) whether to write project or
   global config. Pick `sources[]`:
   - local doc dir: `{ "kind": "filesystem", "ref": "docs", "priority": 10 }`
     (higher priority = preferred when the same content appears in two roots)
   - AGENTS.md / CLAUDE.md: covered by `indexAgentsFiles: true` (default on)
   - source-tree `*.md`: covered by `includeSourceMarkdown: true` (default on)
   - remote sources (npm/git/https) require trust-on-first-use — defer unless
     the user explicitly asks; remote resolvers land in a later phase.
3. **Scaffold.** `kb init [--global] [--source <ref>]... [--dry-run]`.
   Review the `--dry-run` output with the user, then run for real. `kb init`
   refuses to clobber an existing config without `--force`, and gitignores the
   `dbPath`.
4. **Index.** `kb index` → reports files scanned / changed / chunks. First run
   is the cold index; later runs are incremental (mtime → sha256).
5. **Smoke search.** `kb search "<a real term from the docs>" --limit 5` and
   confirm ranked `{path, headingPath, score, snippet}` come back. If empty,
   check `kb config` shows the right `sources` and that the dir has `.md` files.
6. Point the user at the `kb-search` SKILL for everyday retrieval.

## Pitfalls

- Do NOT overwrite an existing config without confirming — use `--force` only
  after the user agrees.
- `dbPath` must be gitignored; `kb init` does this for project configs. For a
  custom `dbPath` outside the project, add the gitignore entry yourself.
- No `sources[]` → `kb index` exits 2. Always seed at least one filesystem source.

## Verification

- `kb config` prints `origin`, `dbAbsPath`, and the resolved `sources` list.
- `kb index` reports `N files … M chunks` and `store.counts()` JSON.
- `kb search "<term>"` returns ranked hits with snippets.