@nzpr/kb 0.1.0 → 0.1.1

package/README.md

@@ -1,38 +1,74 @@
 # Team Knowledge Base CLI
 
-`@nzpr/kb` is the npm package and CLI used by a separate knowledge-authority repository.
+`@nzpr/kb` is a package for managing a knowledge base that agents can read from and that humans can keep curated.
 
-Each KB instance is defined by:
+The core idea is simple:
 
-- `KB_DATABASE_URL`
-- `KB_GITHUB_REPO`
+- initialize a knowledge base
+- propose knowledge
+- publish approved knowledge
+- search the current knowledge
+- ask grounded questions against it
 
-This repository is for the tool itself.
+At the product level, a knowledge base is just a collection of documents, and each document should stay minimal:
 
-The actual knowledge base should live in a separate repository that owns:
+- `title`
+- `text`
 
-- `kb/docs/`
-- issue templates
-- review and approval workflow
-- CI that runs `kb publish`
+Everything else is implementation detail.
 
-Bootstrap that repo with:
+## Public API
+
+The public surface of `@nzpr/kb` is the `kb` CLI.
+
+- `kb init-repo`
+  Initialize a knowledge base workspace.
+
+- `kb create --title TEXT --text TEXT`
+  Propose a new knowledge document or a substantial update.
+
+- `kb publish`
+  Make the current approved documents become the live knowledge base.
+
+- `kb search "<query>"`
+  Return the closest matching knowledge documents.
+
+- `kb ask "<question>"`
+  Return a grounded answer from the closest matching knowledge.
+
+- `kb list`
+  List the current knowledge documents.
+
+- `kb catalog`
+  Return the current knowledge inventory in a machine-friendly form.
+
+- `kb doctor`
+  Check whether the knowledge base is healthy and queryable.
+
+## Lifecycle
+
+The intended workflow is:
+
+1. Initialize a knowledge base.
+2. Propose knowledge.
+3. Review and approve knowledge.
+4. Publish knowledge.
+5. Query knowledge.
+
+## Install
+
+From npm:
 
 ```bash
-kb init-repo --dir /path/to/knowledge-repo
+npm install -g @nzpr/kb
+kb --help
 ```
 
-Or bootstrap and configure it in one step:
+From source:
 
 ```bash
-export GITHUB_TOKEN=...
-kb init-repo \
-  --dir /path/to/knowledge-repo \
-  --repo owner/knowledge-repo \
-  --database-url postgresql://kb:kb@host:5432/kb \
-  --embedding-mode bge-m3-openai \
-  --embedding-api-url https://embeddings.example.com/v1/embeddings \
-  --embedding-model BAAI/bge-m3
+npm install
+npm link
 ```
 
 ## Commands
@@ -45,25 +81,34 @@ kb init-repo \
 - `kb create --title TEXT --text TEXT [--path RELATIVE_PATH]`
 - `kb publish --docs-root PATH`
 
-## Install
+## Knowledge Repo Workflow
 
-From npm:
+In practice, the live knowledge usually lives in a separate repository that owns:
+
+- `kb/docs/`
+- the review flow for proposed knowledge
+- the publish automation
+
+Bootstrap that repo with:
 
 ```bash
-npm install -g @nzpr/kb
-kb --help
+kb init-repo --dir /path/to/knowledge-repo
 ```
 
-From source:
+Or bootstrap and configure it in one step:
 
 ```bash
-npm install
-npm link
+export GITHUB_TOKEN=...
+kb init-repo \
+  --dir /path/to/knowledge-repo \
+  --repo owner/knowledge-repo \
+  --database-url postgresql://kb:kb@host:5432/kb \
+  --embedding-mode bge-m3-openai \
+  --embedding-api-url https://embeddings.example.com/v1/embeddings \
+  --embedding-model BAAI/bge-m3
 ```
 
-## Knowledge Repo Workflow
-
-In the separate knowledge-authority repo:
+Inside that knowledge repo, the normal flow is:
 
 1. Run `kb init-repo` once to scaffold the repo. If you provide `--repo`, `--database-url`, and `GITHUB_TOKEN`, it also configures the target repo and preflights the database.
 2. Open or update a knowledge proposal issue.
@@ -89,7 +134,7 @@ Query commands need:
 export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
 ```
 
-Higher-quality embeddings with a self-hosted OpenAI-compatible `BAAI/bge-m3` server:
+Higher-quality retrieval can use a self-hosted embeddings service:
 
 ```bash
 export KB_EMBEDDING_MODE=bge-m3-openai
@@ -150,7 +195,8 @@ The package is published as `@nzpr/kb`.
 - local validation: `npm test`
 - local package preview: `npm pack --dry-run`
 - GitHub Actions publish: push a tag like `v0.1.0` or run the `npm-publish` workflow manually
-- required repository secret: `NPM_TOKEN`
+- npm authentication: use npm trusted publishing with GitHub Actions OIDC, not a long-lived publish token
+- required npm setup: in npm package settings, configure trusted publishing for `nzpr/kb` and workflow file `.github/workflows/npm-publish.yml`
 
 ## Using From A Knowledge Repo
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nzpr/kb",
-  "version": "0.1.0",
-  "description": "Postgres/pgvector-backed knowledge base CLI for LLM agents and engineering teams.",
+  "version": "0.1.1",
+  "description": "Knowledge base CLI for proposing, publishing, and querying curated agent knowledge.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nzpr/kb.git"