@hraness/kb 0.17.2 → 0.17.3

package/README.md

@@ -3,31 +3,55 @@
 
 [![skills.sh](https://skills.sh/b/hraness/kb)](https://skills.sh/hraness/kb)
 
-a knowledge base for coding agents, built from Markdown, backlinks, semantic
+A knowledge base for coding agents, built from Markdown, backlinks, semantic
 search, and Git context.
+It turns sources, plans, and decisions into inspectable context that agents can
+recover across sessions without coupling application code to the knowledge
+system.
 
-## install
+## Install
+
+Bun 1.3.14 or newer is required.
 
 ```sh
-bun add --global @hraness/kb@0.17.2
+bun add --global @hraness/kb@0.17.3
 ```
 
-## about
+## Why kb
+
+- **Inspect what agents recover.** Markdown and Git stay authoritative,
+  retrieval signals stay distinct, and indexes, embeddings, and graph views
+  remain replaceable.
+- **Keep the application independent.** Application code imports neither the
+  vault nor a hosted knowledge service. Capture and semantic adapters declare
+  their network, browser, native-tool, and model-download effects.
+
+## Create one durable note
+
+From a directory without an existing `kb/` path, this local task creates a
+vault, writes one typed note, and finds it without a network request or
+embedding model:
+
+```sh
+kb init kb
+kb note create notes/parser-contract \
+  --title "Parser contract" --type concept --tag architecture --root kb
+kb search "parser contract" --root kb --mode exact
+```
 
-Turn research, plans, and decisions into reusable context for coding agents.
-Keep sources and repository context beside your code in Markdown and Git. Your
-application stays independent.
+The note is stored at `kb/notes/parser-contract.md`. Exact search reads the
+current Markdown and returns that record. Commit the vault when it should
+travel with the repository.
 
-Search identifiers and metadata. Find meaning locally with QMD. Follow
-backlinks and typed relations. Inspect Git provenance. Search an explicitly
-authorized portfolio of vaults without merging their Markdown or comparing
-their local QMD scores.
+<!-- hraness:kb-landing:end -->
 
-Capture signed-in pages and PDFs. Use the TypeScript SDK and bounded workflows.
+## Links
 
-Markdown and Git stay authoritative. Indexes and graph views are replaceable.
+[Install `@hraness/kb` from npm](https://www.npmjs.com/package/@hraness/kb) ·
+[KB source on GitHub](https://github.com/hraness/kb) ·
+[KB overview](https://hraness.com/kb)
 
-## use
+## Use
 
 ```sh
 kb init kb
@@ -43,13 +67,6 @@ kb portfolio search "parser-v2" --registry kb-portfolio.json \
 kb history search packages/parser --root . --repo .. --json
 ```
 
-## links
-
-[npm](https://www.npmjs.com/package/@hraness/kb) ·
-[github](https://github.com/hraness/kb) ·
-[overview](https://hraness.com/kb)
-<!-- hraness:kb-landing:end -->
-
 ## A knowledge base for your coding agents
 
 > Give coding agents durable, searchable memory beside the repository with plain Markdown, Git history, and replaceable local search.
@@ -113,7 +130,15 @@ kb history search packages/parser/src/index.ts --root kb --repo . --json
 
 ### Preserve evidence and plans as working records
 
-Durable reasoning needs inspectable evidence. `kb clip` can read a public URL, saved HTML, rendered page, a page already open in an authenticated browser, or an existing exact Archive.today snapshot after the direct routes fail. Archive fallback is read-only and always partial. The [capture documentation](<https://github.com/hraness/kb/blob/main/docs/capture.md>) defines the supported routes. A capture writes readable Markdown beside localized assets and `capture.json`, whose manifest records where the material came from, how it was extracted, what was saved, and any warnings. “Complete” describes the selected page surface, not every hidden branch or future version of the site.
+Durable reasoning needs inspectable evidence. `kb clip` can read a public URL,
+saved HTML, rendered page, a page already open in an authenticated browser, or
+an existing exact Archive.today snapshot after the direct routes fail. Archive
+fallback is read-only and always partial. The
+[capture documentation](docs/capture.md) defines the supported routes. A capture
+writes readable Markdown beside localized assets and `capture.json`, whose
+manifest records where the material came from, how it was extracted, what was
+saved, and any warnings. “Complete” describes the selected page surface, not
+every hidden branch or future version of the site.
 
 **Capture a web source or local PDF**
 
@@ -168,6 +193,12 @@ Start with a short inherited `AGENTS.md` path for rules whose omission would mak
 
 Treat the knowledge base as repository-adjacent durable memory. Authored Markdown and Git are the record; catalogs, indexes, embeddings, and graph views are replaceable ways to find and inspect it. Checks can validate structure, captures can preserve a selected surface, and similarity can suggest candidates. None of those mechanisms proves that a source is trustworthy or an explanation is still true. People and agents must revise the knowledge as the repository changes.
 
+## Upgrade to v0.17.3
+
+Version 0.17.3 restructures the README around an inspectable first task,
+explicit operating boundaries, and a shorter path from installation to useful
+output. Runtime APIs and package behavior are unchanged.
+
 ## Upgrade to v0.17.2
 
 Version 0.17.2 improves package discovery through focused npm keywords, a more
@@ -207,7 +238,7 @@ Existing Markdown is not rewritten automatically. Add IDs to maintained legacy
 notes only through reviewed edits, and keep every QMD, graph, portfolio, and
 audit projection disposable.
 
-## Install
+## Installation reference
 
 [Bun](https://bun.sh/docs/installation) is the required runtime.
 
@@ -216,34 +247,35 @@ audit projection disposable.
 Copy this prompt into Codex, Claude Code, or another coding agent:
 
 ```text
-Install the `kb` Agent Skill from hraness/kb with the standard skills CLI. Use
-the skill's runtime instructions to install the exact `@hraness/kb@0.17.2`
-registry release only when the command is missing. Verify it with `kb doctor`
-and `kb --help`, but do not initialize or modify a vault until I ask.
+Install the `kb` Agent Skill from `hraness/kb#v0.17.3` with the standard skills
+CLI. Use the skill's runtime instructions to install the exact
+`@hraness/kb@0.17.3` registry release only when the command is missing. Verify it
+with `kb doctor` and `kb --help`, but do not initialize or modify a vault until
+I ask.
 ```
 
 Install the single public skill with either runner:
 
 ```sh
-npx skills add hraness/kb
-bunx skills add hraness/kb
+npx skills add hraness/kb#v0.17.3
+bunx skills add hraness/kb#v0.17.3
 ```
 
 Both commands discover the same `kb` skill and install it into the selected
 agent runner. Skill installation is inert: it does not initialize a vault,
 refresh a catalog, or edit Markdown. When invoked, the skill uses an existing
 `kb` command or, when the command is missing, checks for Bun and installs the
-CLI from the immutable `@hraness/kb@0.17.2` npm version.
+CLI from the immutable `@hraness/kb@0.17.3` npm version.
 
 The public skills CLI reads `skills/kb/` from the repository. The immutable
-`0.17.2` npm package includes the same tree under
+`0.17.3` npm package includes the same tree under
 `node_modules/@hraness/kb/skills/kb/`, and the package check verifies that the
 installed skill is byte-identical to the repository source.
 
 Install the two global commands with Bun:
 
 ```sh
-bun add --global @hraness/kb@0.17.2
+bun add --global @hraness/kb@0.17.3
 kb --help
 kb-evaluation-builder --help
 ```
@@ -251,7 +283,7 @@ kb-evaluation-builder --help
 The same registry package can be installed with npm:
 
 ```sh
-npm install --global --ignore-scripts @hraness/kb@0.17.2
+npm install --global --ignore-scripts @hraness/kb@0.17.3
 kb --help
 ```
 
@@ -264,7 +296,7 @@ reviewed and enabled; run `kb doctor` to inspect the resulting capabilities.
 For programmatic use, add the exact npm version to a Bun project:
 
 ```sh
-bun add --exact @hraness/kb@0.17.2
+bun add --exact @hraness/kb@0.17.3
 ```
 
 The resulting dependency should remain exact:
@@ -272,12 +304,12 @@ The resulting dependency should remain exact:
 ```json
 {
   "dependencies": {
-    "@hraness/kb": "0.17.2"
+    "@hraness/kb": "0.17.3"
   }
 }
 ```
 
-Version 0.17.2 retains two public GitHub dependencies:
+Version 0.17.3 retains two public GitHub dependencies:
 `@steipete/sweet-cookie` at Hraness release `v0.4.2` for the cookie-scope safety
 fork, and `@tobilu/qmd` at commit
 `aa993dceb3ef8cfb71d470554ca437570f5a2b3c` for store-local model behavior. A
@@ -540,9 +572,9 @@ a vault. The package smoke test keeps future tagged packages byte-identical to
 that source tree.
 
 ```sh
-npx skills add hraness/kb
+npx skills add hraness/kb#v0.17.3
 # or
-bunx skills add hraness/kb
+bunx skills add hraness/kb#v0.17.3
 ```
 
 The skill invokes the installed `kb` command without depending on a repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/kb",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
   "license": "MIT",
   "contentPolicy": {

package/skills/kb/SKILL.md

@@ -31,7 +31,7 @@ missing:
 ```sh
 command -v kb >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global @hraness/kb@0.17.2
+  bun add --global @hraness/kb@0.17.3
 }
 kb --help
 ```