@nzpr/kb 0.1.12 → 0.1.14

package/README.md

@@ -1,164 +1,91 @@
-# Team Knowledge Base CLI
+# @nzpr/kb
 
-`@nzpr/kb` is a package for managing a knowledge base that agents can read from and that humans can keep curated.
+`@nzpr/kb` is a CLI for a curated knowledge base.
 
-The core idea is simple:
-
-- initialize a knowledge base
-- propose knowledge
-- publish approved knowledge
-- search the current knowledge
-- ask grounded questions against it
-
-At the product level, a knowledge base is just a collection of documents, and each document should stay minimal:
+A knowledge base is just a set of documents:
 
 - `title`
 - `text`
 
 Everything else is implementation detail.
 
-## Public API
-
-The public surface of `@nzpr/kb` is the `kb` CLI.
-
-- `kb init-repo`
-  Initialize a knowledge base workspace.
-  Use `kb init-repo --interactive` for a guided setup flow.
-  Use `--layout repo-root` when this repository is itself the KB.
-
-- `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.
+## Core Idea
 
-- `kb catalog`
-  Return the current knowledge inventory in a machine-friendly form.
+Use `@nzpr/kb` to do five things:
 
-- `kb doctor`
-  Check whether the knowledge base is healthy and queryable.
+1. initialize a knowledge repo
+2. propose knowledge
+3. publish approved knowledge
+4. search knowledge
+5. answer questions from knowledge
 
-## 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
+## Public API
 
-From npm:
+The public surface is the `kb` CLI.
 
 ```bash
-npm install -g @nzpr/kb
-kb --help
+kb init-repo
+kb create --title "..." --text "..."
+kb publish --docs-root ./docs
+kb search "..."
+kb ask "..."
+kb list
+kb catalog --json
+kb doctor
 ```
 
-From source:
+## Install
 
 ```bash
-npm install
-npm link
+npm install -g @nzpr/kb
 ```
 
-## Commands
-
-- `kb init-repo [--dir PATH] [--repo OWNER/REPO]`
-- `kb search "<terms>"`
-- `kb ask "<question>"`
-- `kb list`
-- `kb catalog [--json]`
-- `kb create --title TEXT --text TEXT [--path RELATIVE_PATH]`
-- `kb publish --docs-root PATH`
-
-## Knowledge Repo Workflow
-
-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:
+Node.js 20+ is required.
 
-```bash
-kb init-repo --dir /path/to/knowledge-repo
-```
+## Minimal Usage
 
-If you want the CLI to walk you through setup and tell you what to do next:
+### 1. Initialize a Knowledge Repo
 
 ```bash
 kb init-repo --interactive
 ```
 
-Layout options:
-
-- `--layout repo-root` puts documents in `docs/`
-- `--layout nested-kb` puts documents in `kb/docs/`
-
-For a dedicated knowledge repository, prefer `--layout repo-root`.
+For a dedicated knowledge repo, use repo-root layout so documents live in `docs/`.
 
-Or bootstrap and configure it in one step:
+### 2. Propose Knowledge
 
 ```bash
+export KB_GITHUB_REPO=owner/repo
 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
-```
-
-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.
-3. Review and approve it there.
-4. Materialize it into the configured docs directory.
-5. After merge, that repo's CI runs `kb publish` against that docs directory.
 
-`kb init-repo` is safe to rerun. It reports bootstrap status for:
+kb create \
+  --title "Example Rule" \
+  --text "Write the exact knowledge text here."
+```
 
-- local scaffold creation
-- knowledge document layout selection
-- database preflight and schema initialization
-- GitHub repo labels, variables, and secrets
+This creates a GitHub issue proposal.
 
-In interactive mode it also:
+### 3. Approve Knowledge
 
-- asks which repo and directory you want to initialize
-- asks whether to wire GitHub setup now
-- asks whether to verify the database now
-- collects embedding settings if you want remote embeddings
-- prints the next actions after initialization
+Add the `kb-approved` label to the proposal issue.
 
-If one remote step fails, the scaffold still stays in place and the command tells you what to rerun.
+That triggers automation which:
 
-## Runtime
+1. writes the Markdown document
+2. opens a PR
+3. lets merge trigger publish
 
-Node.js 20+ is required.
+### 4. Publish Knowledge
 
-Query commands need:
+Publishing reads local docs and writes them to the database.
 
 ```bash
-export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
+export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB
+
+kb publish --docs-root ./docs
 ```
 
-Higher-quality retrieval can use a self-hosted embeddings service:
+Optional higher-quality embeddings:
 
 ```bash
 export KB_EMBEDDING_MODE=bge-m3-openai
@@ -167,83 +94,58 @@ export KB_EMBEDDING_MODEL=BAAI/bge-m3
 export KB_EMBEDDING_API_KEY=...
 ```
 
-If `KB_EMBEDDING_MODE` is omitted, the CLI uses local hash embeddings for development.
-
-Publishing uses the local docs directory and the database only. It does not need GitHub credentials.
-
-When `kb init-repo` is given `--repo`, it uses the same token to:
-
-- enable issues in the target repo
-- set GitHub Actions workflow permissions to write and allow Actions to create PRs
-- create or update the `kb-entry` and `kb-approved` labels
-- write repository secrets and variables
-- verify and initialize the target database schema if `--database-url` is provided
-
-For the GitHub setup step, that token must have repository admin access. A plain write token is not enough for Actions settings and repo secrets.
-
-If you run `kb init-repo` without the repo or database inputs, it still scaffolds the knowledge repo and prints exactly which remote bootstrap inputs are still pending.
-
-## Quick Start
+### 5. Query Knowledge
 
 ```bash
-export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
-docker compose -f docker-compose.pgvector.yml up -d
-kb publish --docs-root ./docs
-kb catalog --json
-kb search "deployment rule"
-```
-
-Each Markdown file is indexed as one document and one vector row. Keep documents simple: one title and one body.
+export KB_DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB
 
-## Optional Split Mode
-
-If you later want separate entities, isolated databases, or a dedicated content repo, you can use `kb create` with:
-
-```bash
-export KB_GITHUB_REPO=org/knowledge-content
-export GITHUB_TOKEN=...
+kb search "deployment rule"
+kb ask "How do I approve a knowledge proposal?"
+kb list
+kb catalog --json
+kb doctor
 ```
 
-That path is optional. The default assumption is that you work in one repo.
-
-## npm Release
+## Standard Workflow
 
-The package is published as `@nzpr/kb`.
+The intended flow is:
 
-- 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
-- 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`
+1. `kb init-repo`
+2. `kb create`
+3. review the issue
+4. add `kb-approved`
+5. merge the generated PR
+6. let CI run `kb publish`
+7. query with `kb search` or `kb ask`
 
-## Using From A Knowledge Repo
+## Repo Bootstrap
 
-The knowledge-authority repo should install this package in CI and use it to sync its configured docs directory into the vector database. For a dedicated KB repo with `--layout repo-root`, that directory is `docs/`:
+If you want `kb init-repo` to configure the target GitHub repo too:
 
 ```bash
-npm install -g @nzpr/kb
-export KB_GITHUB_REPO=owner/repo
 export GITHUB_TOKEN=...
-kb publish --docs-root ./docs
-```
-
-Or scaffold that repo first:
-
-```bash
-kb init-repo --dir .
-```
 
-If you want init to configure the target repo too:
-
-```bash
-export GITHUB_TOKEN=...
-export KB_REPO_AUTOMATION_TOKEN=...
 kb init-repo \
-  --dir . \
+  --dir /path/to/knowledge-repo \
   --repo owner/knowledge-repo \
-  --database-url postgresql://kb:kb@host:5432/kb \
+  --database-url postgresql://USER:PASSWORD@HOST:5432/DB \
   --embedding-mode bge-m3-openai \
   --embedding-api-url https://embeddings.example.com/v1/embeddings \
-  --embedding-model BAAI/bge-m3 \
-  --embedding-api-key YOUR_KEY
+  --embedding-model BAAI/bge-m3
 ```
+
+For this setup step, the token must have repository admin access.
+
+`kb init-repo` configures:
+
+- issue templates
+- GitHub labels
+- GitHub Actions workflow permissions
+- repo secrets and variables
+- knowledge publish workflow
+
+## Notes
+
+- Keep each document minimal: one title, one body.
+- `kb publish` does not need GitHub credentials.
+- The package published to npm is `@nzpr/kb`.

package/lib/kb-proposals.js

@@ -71,7 +71,9 @@ export function writeProposalDocument({ issueNumber, issueTitle, issueBody, docs
       "",
       `Source issue title: ${issueTitle}`,
       "",
-      `Document path: \`${relativePath}\``
+      `Document path: \`${relativePath}\``,
+      "",
+      `Closes #${issueNumber}`
     ].join("\n")
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nzpr/kb",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Knowledge base CLI for proposing, publishing, and querying curated agent knowledge.",
   "repository": {
     "type": "git",