@hraness/kb 0.18.0 → 0.18.1

package/README.md

@@ -14,34 +14,67 @@ system.
 Bun 1.3.14 or newer is required.
 
 ```sh
-bun add --global @hraness/kb@0.18.0
+bun add --global @hraness/kb@0.18.1
+kb --help
 ```
 
-## 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
+## Keep one decision available to the next session
 
-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:
+Suppose a parser must stop retrying after three attempts. Record that constraint
+in a note, then link the plan that will implement it:
 
-```sh
+```shell
 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
+  --title "Parser contract" --type concept --tag architecture \
+  --body "Parser retries stop after three attempts." --root kb
+kb note create plans/parser-v2 \
+  --title "Parser v2" --type plan \
+  --body "The plan implements [[notes/parser-contract|the parser contract]]." \
+  --root kb
+```
+
+The first `kb note create` command stores ordinary Markdown at
+`kb/notes/parser-contract.md` and assigns its stable `document_id`. Add the
+exact code boundary to that note's frontmatter so path lookup can recover it:
+
+```yaml
+repository_scopes:
+  - packages/parser
 ```
 
-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.
+Commit the vault with the repository. The Markdown and its Git history are the
+durable record.
+
+## Recover the stopped session
+
+In a later session, start from the code path and inspect each independent
+signal:
+
+```shell
+kb context packages/parser/src/index.ts --root kb --repo .
+kb search "why parser retries stop" --root kb --mode exact \
+  --history --repo .
+kb backlinks notes/parser-contract --root kb
+kb history notes/parser-contract --root kb --repo .
+```
+
+| Signal | What it recovers |
+| --- | --- |
+| Markdown | The current parser constraint in the file you can review and edit. |
+| Backlinks | The plan that explicitly links to the constraint. |
+| Exact search | The current note matched from its words, without a network request or embedding model. |
+| Repository context | Inherited `AGENTS.md` guides and records scoped to `packages/parser`. |
+| Git history | The commits and bounded co-change evidence associated with the note. |
+
+Together, those views recover the persisted decision, related plan, applicable
+rules, and provenance needed to resume the work. They do not reconstruct
+private chat or prove that the note is still correct. Open the returned
+Markdown and guides before acting on them.
+
+The boundaries stay visible: Markdown and Git are authoritative, backlinks and
+indexes are replaceable views, and Git work is opt-in. Application code imports
+neither the vault nor a hosted knowledge service.
 
 <!-- hraness:kb-landing:end -->
 
@@ -51,22 +84,6 @@ travel with the repository.
 [KB source on GitHub](https://github.com/hraness/kb) ·
 [KB overview](https://hraness.com/kb)
 
-## Use
-
-```sh
-kb init kb
-kb clip https://example.com/article --output articles
-kb pdf ./report.pdf --output articles
-kb percolate notes/topic --root .
-kb context packages/parser/src/index.ts --root kb --repo .
-kb list --where type=plan --scope packages/parser --root .
-kb links notes/topic --root . --direction both
-kb search "parser-v2" --root . --mode exact
-kb portfolio search "parser-v2" --registry kb-portfolio.json \
-  --workspace .. --shared
-kb history search packages/parser --root . --repo .. --json
-```
-
 ## 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.
@@ -193,63 +210,6 @@ 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.18.0
-
-Version 0.18.0 adds a review-only adoption seam for exact dependency closures
-from an Oh working authority. Trusted host code creates a
-`createOhAdoptionPreparerV1` facade with the expected binding and head,
-destination, rights clearance, review route, and conflict policy. The narrow
-`prepare` call accepts only a capsule plus transformation and redaction
-disclosures, returns deeply immutable deterministic Markdown and manifest
-bytes with status `prepared`, and has no vault, Git, Oh-store, or promotion
-capability. KB pins `@hraness/oh` v0.2.0 and delegates closure integrity to its
-official store verifier.
-
-## 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
-specific README opening, and direct links between npm, GitHub, and the project
-overview. Runtime APIs and package behavior are unchanged.
-
-## Upgrade to v0.17.1
-
-Version 0.17.1 adds the public `@hraness/kb` npm installation path without
-changing the runtime API introduced in 0.17.0. Bun `1.3.14` or newer is now an
-explicit package requirement. Consumers should review the package's declared
-dual-use capture boundary and the lifecycle scripts used by optional browser
-and native search adapters before enabling those scripts.
-
-## Upgrade to v0.17.0
-
-Version 0.17 adds selected portfolio federation, stable note identities,
-qualified external relations, search rules, capture inspection, and untrusted
-context packing. Consumers with typed fixtures or custom capture writers should
-make these migrations before upgrading:
-
-- Capture writers now emit manifest schema v4 and must provide the stored
-  document `path`, exact UTF-8 `bytes`, and lowercase SHA-256 digest. The reader
-  can inspect schema v1-v3, but verification reports their document integrity as
-  unavailable instead of success.
-- `DecisionContextOutput.search` has been removed. Consume the bounded untrusted
-  `context` projection and its `truncated` flag instead of transporting the raw
-  search result into an agent prompt.
-- `VaultAnalysis` fixtures must include `externalAuthoredRelations`, even when
-  the value is an empty array. This keeps qualified authored edges distinct
-  from locally resolved graph edges.
-- `createNote` and `kb note create` now assign `document_id` to new ordinary
-  notes. Preserve that ID across renames and update snapshots that intentionally
-  assert the generated frontmatter.
-
-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.
-
 ## Installation reference
 
 [Bun](https://bun.sh/docs/installation) is the required runtime.
@@ -259,9 +219,9 @@ audit projection disposable.
 Copy this prompt into Codex, Claude Code, or another coding agent:
 
 ```text
-Install the `kb` Agent Skill from `hraness/kb#v0.18.0` with the standard skills
+Install the `kb` Agent Skill from `hraness/kb#v0.18.1` with the standard skills
 CLI. Use the skill's runtime instructions to install the exact
-`@hraness/kb@0.18.0` registry release only when the command is missing. Verify it
+`@hraness/kb@0.18.1` 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.
 ```
@@ -269,25 +229,25 @@ I ask.
 Install the single public skill with either runner:
 
 ```sh
-npx skills add hraness/kb#v0.18.0
-bunx skills add hraness/kb#v0.18.0
+npx skills add hraness/kb#v0.18.1
+bunx skills add hraness/kb#v0.18.1
 ```
 
 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.18.0` npm version.
+CLI from the immutable `@hraness/kb@0.18.1` npm version.
 
 The public skills CLI reads `skills/kb/` from the repository. The immutable
-`0.18.0` npm package includes the same tree under
+`0.18.1` 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.18.0
+bun add --global @hraness/kb@0.18.1
 kb --help
 kb-evaluation-builder --help
 ```
@@ -295,7 +255,7 @@ kb-evaluation-builder --help
 The same registry package can be installed with npm:
 
 ```sh
-npm install --global --ignore-scripts @hraness/kb@0.18.0
+npm install --global --ignore-scripts @hraness/kb@0.18.1
 kb --help
 ```
 
@@ -308,7 +268,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.18.0
+bun add --exact @hraness/kb@0.18.1
 ```
 
 The resulting dependency should remain exact:
@@ -316,12 +276,12 @@ The resulting dependency should remain exact:
 ```json
 {
   "dependencies": {
-    "@hraness/kb": "0.18.0"
+    "@hraness/kb": "0.18.1"
   }
 }
 ```
 
-Version 0.18.0 retains three public GitHub dependencies: `@hraness/oh` at
+Version 0.18.1 retains three public GitHub dependencies: `@hraness/oh` at
 immutable release `v0.2.0` for closure verification,
 `@steipete/sweet-cookie` at Hraness release `v0.4.2` for the cookie-scope safety
 fork, and `@tobilu/qmd` at commit
@@ -585,9 +545,9 @@ a vault. The package smoke test keeps future tagged packages byte-identical to
 that source tree.
 
 ```sh
-npx skills add hraness/kb#v0.18.0
+npx skills add hraness/kb#v0.18.1
 # or
-bunx skills add hraness/kb#v0.18.0
+bunx skills add hraness/kb#v0.18.1
 ```
 
 The skill invokes the installed `kb` command without depending on a repository
@@ -597,3 +557,69 @@ effect. The repository's phase-orchestration skill remains available to local
 repository agents but is marked internal, so public skill discovery omits it.
 
 See [Design](docs/design.md), [Portfolio federation](docs/portfolio.md), [Agent workflow](docs/agent-workflow.md), [PDF capture](docs/pdf.md), and [Contributing](CONTRIBUTING.md) for the durable contracts and development gate. hraness/kb is available under the [MIT License](LICENSE).
+
+## Release notes
+
+### Upgrade to v0.18.1
+
+Version 0.18.1 restructures the public README and hosted projection around one
+durable note, the exact recovery workflow, inspectable retrieval signals, and
+explicit authority boundaries. Runtime APIs and package behavior are
+unchanged.
+
+### Upgrade to v0.18.0
+
+Version 0.18.0 adds a review-only adoption seam for exact dependency closures
+from an Oh working authority. Trusted host code creates a
+`createOhAdoptionPreparerV1` facade with the expected binding and head,
+destination, rights clearance, review route, and conflict policy. The narrow
+`prepare` call accepts only a capsule plus transformation and redaction
+disclosures, returns deeply immutable deterministic Markdown and manifest
+bytes with status `prepared`, and has no vault, Git, Oh-store, or promotion
+capability. KB pins `@hraness/oh` v0.2.0 and delegates closure integrity to its
+official store verifier.
+
+### 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
+specific README opening, and direct links between npm, GitHub, and the project
+overview. Runtime APIs and package behavior are unchanged.
+
+### Upgrade to v0.17.1
+
+Version 0.17.1 adds the public `@hraness/kb` npm installation path without
+changing the runtime API introduced in 0.17.0. Bun `1.3.14` or newer is now an
+explicit package requirement. Consumers should review the package's declared
+dual-use capture boundary and the lifecycle scripts used by optional browser
+and native search adapters before enabling those scripts.
+
+### Upgrade to v0.17.0
+
+Version 0.17 adds selected portfolio federation, stable note identities,
+qualified external relations, search rules, capture inspection, and untrusted
+context packing. Consumers with typed fixtures or custom capture writers should
+make these migrations before upgrading:
+
+- Capture writers now emit manifest schema v4 and must provide the stored
+  document `path`, exact UTF-8 `bytes`, and lowercase SHA-256 digest. The reader
+  can inspect schema v1-v3, but verification reports their document integrity as
+  unavailable instead of success.
+- `DecisionContextOutput.search` has been removed. Consume the bounded untrusted
+  `context` projection and its `truncated` flag instead of transporting the raw
+  search result into an agent prompt.
+- `VaultAnalysis` fixtures must include `externalAuthoredRelations`, even when
+  the value is an empty array. This keeps qualified authored edges distinct
+  from locally resolved graph edges.
+- `createNote` and `kb note create` now assign `document_id` to new ordinary
+  notes. Preserve that ID across renames and update snapshots that intentionally
+  assert the generated frontmatter.
+
+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.

package/package.json

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

package/skills/kb/SKILL.md

@@ -3,12 +3,13 @@ name: kb
 description: >-
   Operate a hraness/kb local-first Markdown knowledge base for coding-agent
   memory. Use when a user asks to search or query a KB or Obsidian vault; load
-  repository context, plans, decisions, concepts, backlinks, semantic search,
-  or Git provenance; save, clip, scrape, or archive a URL, article, social
-  thread, signed-in browser page, or PDF as auditable Markdown; create or
-  update a durable plan in the vault; or refresh, check, percolate, and
-  maintain its knowledge graph. Do not use for generic web research, generic
-  PDF reading, or ordinary planning that will not use a hraness/kb vault.
+  or recover repository context, plans, decisions, concepts, backlinks,
+  semantic search, or Git provenance from an earlier coding session; save,
+  clip, scrape, or archive a URL, article, social thread, signed-in browser
+  page, or PDF as auditable Markdown; create or update a durable plan in the
+  vault; or refresh, check, percolate, and maintain its knowledge graph. Do not
+  use for generic web research, generic PDF reading, or ordinary planning that
+  will not use a hraness/kb vault.
 ---
 
 # Work with KB
@@ -31,7 +32,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.18.0
+  bun add --global @hraness/kb@0.18.1
 }
 kb --help
 ```
@@ -50,7 +51,7 @@ Initialize or mutate a vault only when the user's request requires that change.
 
 | User intent | Read |
 | --- | --- |
-| Find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Recover work from an earlier session, find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
 | Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
 | Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
 | Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |

package/skills/kb/references/query.md

@@ -14,6 +14,27 @@ authority; search scores, metadata rows, and graph results are derived views.
 - Pass the resolved path to every `--root`; do not scan a repository root merely
   because that is where the agent session started.
 
+## Recover a stopped session
+
+When the user asks to resume earlier work, begin with the path being changed.
+Keep each retrieval signal separate so the agent can inspect why a record was
+returned:
+
+```sh
+kb context packages/parser/src/index.ts --root "$KB_ROOT" --repo "$KB_REPO"
+kb search "why parser retries stop" --root "$KB_ROOT" --mode exact \
+  --history --repo "$KB_REPO" --json
+kb backlinks notes/parser-contract --root "$KB_ROOT" --json
+kb history notes/parser-contract --root "$KB_ROOT" \
+  --repo "$KB_REPO" --json
+```
+
+Replace the example path, query, and note ID with values from the current task.
+Read the inherited guides and authoritative Markdown returned by these views.
+Use the backlink to inspect related plans and use Git history as provenance,
+not as proof that the note remains correct. This workflow recovers only context
+that was persisted in files or Git; it does not reconstruct private chat.
+
 ## Choose the retrieval lane
 
 - Repository file or directory: run `kb context` first. Read its inherited