npm package: @nzpr/kb
Description: Knowledge base CLI for querying and curating agent knowledge.
Latest version: 0.1.27

# @nzpr/kb

`@nzpr/kb` is a CLI for working with a GitHub-backed knowledge base that is synced into a vector database.

A knowledge entry is intentionally minimal:

- `title`
- `text`

The repo is the authority for approved knowledge. The vector database is a published search index built from that repo.

## Install

```bash
npm install -g @nzpr/kb
```

Node.js `20+` is required.

## Commands

```bash
kb init-repo [--interactive] [--layout repo-root|nested-kb] [--dir PATH] [--repo OWNER/REPO]
kb create --title TEXT [--text TEXT|--text-file PATH|--text-stdin] [--path RELATIVE_PATH] [--repo OWNER/REPO] [--yes|--create-anyway] [--json]
kb edit --title TEXT [--text TEXT|--text-file PATH|--text-stdin] [--path RELATIVE_PATH] [--repo OWNER/REPO] [--yes] [--json]
kb delete [--path RELATIVE_PATH] [--title TEXT] [--text TEXT] [--reason TEXT] [--repo OWNER/REPO] [--yes] [--json]
kb get <doc_id|path|title> [--json]
kb status <doc_id|path|title> [--repo OWNER/REPO] [--json]
kb search <query> [--json]
kb ask <question>
kb list [--json] [--with-proposals]
kb catalog [--json]
kb publish [--docs-root PATH] [--knowledge-root PATH]
kb doctor
```

Run `kb <command> --help` for exact runtime requirements.

## Core Model

There are three separate surfaces:

- GitHub repo: the source of truth for approved knowledge documents
- GitHub issues and workflows: the proposal, review, approval, and materialization pipeline
- Vector database: the published retrieval index used by `kb search` and `kb ask`

That separation matters:

- creators do not write to the default branch directly
- reviewers approve knowledge on the issue
- GitHub Actions writes the approved Markdown into the repo
- `kb publish` syncs the repo state into the vector DB

## Knowledge Format

Knowledge is stored as Markdown in the knowledge repo under `docs/` or `kb/docs/`.

Each document should just be:

```md
# Title

Text that should be retrieved by search.
```

During publish, the title and body are extracted from the Markdown document and written into the database as one searchable document row.

Document paths are always relative to the docs root.

- use `standards/example.md`
- do not use `docs/standards/example.md`

## Read Workflow

Most agents and applications only need read access to the published KB.

```bash
export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb ask "How do we manage knowledge?"
kb search "knowledge approval"
kb get how-we-manage-knowledge
kb status how-we-manage-knowledge
kb list --with-proposals
```

What the read side does:

- `kb ask` returns the best matching document text when there is a strong match
- `kb ask` prints a short no-match response when nothing relevant is in the DB
- `kb search` shows the closest matching documents and their paths
- `kb get` prints the full live document body from the DB
- `kb status` shows the live document and any open GitHub proposal for the same entry
- `kb list --with-proposals` shows live entries and open KB issues together
- readers do not need GitHub access

For automation, prefer `--json` on `search`, `get`, `status`, and `list`.

## Proposal Workflow

Use the write commands only when the knowledge itself needs to change:

- `kb create`: propose a new entry
- `kb edit`: revise an existing entry
- `kb delete`: remove an obsolete entry

```bash
export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...

kb create \
  --title "How we manage knowledge" \
  --text-file ./knowledge.txt
```

What `kb create` does:

- works against the remote GitHub knowledge repo
- inspects existing remote documents
- computes semantic and lexical similarity against existing entries
- shows close matches
- lets you choose create, edit, or cancel when run interactively
- supports non-interactive runs with `--create-anyway` or `--yes`
- supports large bodies through `--text-file` and `--text-stdin`
- returns structured machine-readable output with `--json`

What this prevents:

- duplicate entries for the same topic
- creating a second knowledge document when an update to an existing one is the right move

Idempotence:

- if the same open proposal already exists, `kb create` returns that issue instead of opening another one
- transient GitHub `5xx` and `429` failures are retried automatically with backoff

If you already know the target path for the new document, pass `--path`.
That path is relative to the docs root, not repo root.

## Edit Workflow

Use `kb edit` when you are not satisfied with existing knowledge and want to revise it.

```bash
export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...

kb edit \
  --title "Updated knowledge title" \
  --text-stdin < ./revised-knowledge.txt
```

What `kb edit` does:

- works against the remote GitHub knowledge repo
- finds the best existing matching document semantically
- lets you confirm which existing document should be edited
- supports fully scripted runs with `--yes`
- reopens the prior proposal issue for that exact document path
- rewrites the issue body with the new title and text
- removes `kb-approved` so approval must be explicit and fresh
- returns JSON with `--json`

If you already know the exact document to revise, pass `--path`.

What this prevents:

- editing the wrong document by accident
- silently creating a second document instead of revising the real one
- preserving stale approval after the content has changed

Idempotence:

- if the same open edit proposal already exists, `kb edit` returns it
- if a different proposal is already open for that path, `kb edit` fails instead of creating ambiguity

## Delete Workflow

Use `kb delete` when an entry should be removed entirely.

```bash
kb delete \
  --title "How we do CI/CD" \
  --text "deploy rollback health checks"
```

Or, if you already know the exact document:

```bash
kb delete --path entries/how-we-do-ci-cd.md --reason "Superseded by service-specific knowledge."
```

That path is also relative to the docs root.

What `kb delete` does:

- works against the remote GitHub knowledge repo
- finds the best existing matching document, or uses `--path` exactly
- opens or reopens a delete proposal issue for that document path
- marks the GitHub issue title as `kb: [DELETE] ...`
- keeps approval manual through `kb-approved`
- supports `--yes` for scripted target selection
- returns JSON with `--json`

Delete is repo-first:

- the PR removes the Markdown document from the knowledge repo
- the next publish removes that document from the vector DB

If one document needs to become two, do it as a composition:

1. create the first new entry with `kb create`
2. create the second new entry with `kb create`
3. remove the original entry with `kb delete`

That keeps the model simple:

- add knowledge with `kb create`
- revise knowledge with `kb edit`
- remove knowledge with `kb delete`

## Duplicate Handling And State Visibility

Duplicate protection is part of the authoring flow.

`kb create`:

- looks for semantically similar existing knowledge
- shows likely matches before creating anything
- lets you cancel or switch to editing one of those entries
- can be forced non-interactively with `--create-anyway` or `--yes`

`kb edit`:

- looks for the best existing matching knowledge
- asks you to confirm the edit target when more than one plausible match exists
- is anchored to the existing document path once selected
- fails if a different proposal is already open for that path

`kb delete`:

- can resolve the target semantically when you do not pass `--path`
- asks you to confirm which existing document is being removed

Approval is always path-specific:

- the issue body stores `### Relative Path`
- the workflow materializes exactly that document path
- the publish step syncs the repo state that exists after merge

State inspection commands:

- `kb get <ref>` prints the full live entry body from the DB
- `kb status <ref>` shows the live entry plus any open proposal issue for the same document path
- `kb list --with-proposals` shows the whole live set together with pending KB issues
- each of those commands supports `--json` for agent use

## Review and Approval Workflow

Review happens on GitHub issues.

The standard review loop is:

1. creator runs `kb create`, `kb edit`, or `kb delete`
2. KB proposal issue is created or reopened
3. reviewer edits the issue if needed
4. reviewer manually adds `kb-approved`
5. GitHub Actions materializes the approved file changes as a PR
6. the PR auto-merges
7. publish runs and syncs the repo into the vector DB

Important rule:

- approval is manual and explicit through the `kb-approved` label
- reopened edit and delete issues do not keep approval; `kb-approved` must be added again

## GitHub Actions Workflows

`kb init-repo` scaffolds two workflows into the knowledge repo:

### `kb-issue-to-pr`

Triggered on:

- issue labeled

Behavior:

- runs only when the added label is `kb-approved`
- converts the approved issue into the exact Markdown file changes
- creates a PR with those file changes
- auto-merges the PR
- refreshes `main` and runs `kb publish` in the same workflow so the DB updates even though the merge was performed by GitHub Actions
- comments back on the issue with the PR number

### `kb-publish`

Triggered on:

- push to `main` that changes `docs/**` or workflow files
- manual `workflow_dispatch`

Behavior:

- checks out the repo
- installs `@nzpr/kb`
- runs `kb publish`
- writes the live repo state into the vector DB

Issue creation and publishing are intentionally separate:

- authoring commands talk to GitHub
- publish talks to the DB
- merged repo state is what gets indexed

## Vector Database and Publish

`kb publish` is the sync step from repo to retrieval index.

```bash
export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb publish --docs-root ./docs
```

What publish does:

- reads every Markdown doc under the docs root
- extracts title and body
- computes embeddings for each document
- upserts documents into the database
- removes database rows for docs that no longer exist in the repo

The result is:

- repo state and database state stay aligned
- the vector DB reflects what is actually approved and merged

## Semantic Search

`kb search` and `kb ask` query the vector database, not GitHub.

```bash
export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb search "deployment rollback rule"
kb ask "How do we approve a knowledge proposal?"
```

How retrieval works:

- lexical search over document text
- semantic search over stored embeddings
- score merge of lexical and semantic signals
- weak matches are filtered out

`kb ask` currently returns the best retrieved guidance with sources. It is a retrieval wrapper, not a generative answer engine.

## Embeddings

Authoring commands and publish use the same embedding runtime configuration when semantic matching is needed.

Supported modes:

- `local-hash`
- `bge-m3-openai`

Example remote embedding config:

```bash
export KB_EMBEDDING_MODE=bge-m3-openai
export KB_EMBEDDING_API_URL=https://embeddings.example.com/v1/embeddings
export KB_EMBEDDING_MODEL=BAAI/bge-m3
export KB_EMBEDDING_API_KEY=...
```

Use `local-hash` for cheap local matching. Use `bge-m3-openai` for higher quality semantic matching and search.

## Consumer Workflow

For users or agents consuming knowledge, the common flow is:

```bash
export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB

kb search "deployment rule"
kb ask "How do we deploy safely?"
kb get deployment-safety
kb status deployment-safety
kb list
kb list --with-proposals
kb catalog --json
kb doctor
```

That is the normal path. Most usage should be `kb search`, `kb ask`, `kb get`, and `kb status`, not `kb create` or `kb edit`.

## Repo Bootstrap

Use `kb init-repo` to scaffold a knowledge repo and configure the GitHub automation.

```bash
kb init-repo --interactive
```

It creates:

- issue template for KB proposals
- `kb-issue-to-pr` workflow
- `kb-publish` workflow
- docs directory scaffold

For remote bootstrap, `kb init-repo --repo ...` needs a GitHub token with repository admin access.

## Notes

- `kb publish` does not need GitHub credentials.
- `kb create` and `kb edit` are GitHub-first authoring commands.
- The repo is the approved truth; the vector DB is the published index.
- If the repo and DB ever diverge, rerun publish from the repo state.