diff --git a/AGENTS.md b/AGENTS.md
index a650e09..9ade036 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,7 @@
 
 - Use Bun 1.3.14 for repository commands and keep the authored Markdown compatible with Obsidian and ordinary text tooling.
 - Follow `WRITING.md` for internal prose and `STYLE.md` for public prose.
+- Follow the shared [Hraness README guidelines](https://github.com/hraness/.github/blob/main/README_GUIDELINES.md) for the README trust path and its website projection. Adapt the structure to KB's local-data and Agent Skill boundaries instead of copying a fixed template.
 - Apply unreasonably robust programming when agent work is cheap. Model invalid states out of existence, parse every foreign value from `unknown`, and pair readable deterministic regressions with property tests for parsing, resolution, ordering, path confinement, and round trips.
 - Deliver changes to `main` through a current-head pull request. Keep the stable `Required` CI job green, resolve every review thread, and serialize merges. Human approval stays optional while one regular maintainer would otherwise self-review. Never force-push or bypass the gate.
 - Pin Hraness dependencies to reviewed immutable releases or full commits. Never connect repositories through sibling paths, Git submodules, or coordinated `main` assumptions; upgrade each consumer independently.
diff --git a/README.md b/README.md
index 0c62365..d76ded3 100644
--- a/README.md
+++ b/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
 ```
 
-## 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:
 
-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.
+```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
+```
 
-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.
+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.
+
+<!-- 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
-
-[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)
-<!-- 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.
@@ -207,7 +224,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.
 
diff --git a/scripts/npm-release-workflow.test.ts b/scripts/npm-release-workflow.test.ts
index a836641..ba47e05 100644
--- a/scripts/npm-release-workflow.test.ts
+++ b/scripts/npm-release-workflow.test.ts
@@ -410,7 +410,7 @@ describe("canonical npm package identity", () => {
       });
       const verified = await verifyNpmPackageIdentity(validInput);
       expect(verified.fileCount).toBe(200);
-      expect(verified.unpackedBytes).toBe(4_860_696);
+      expect(verified.unpackedBytes).toBe(4_861_264);
       expect(verified.sourceArchiveSha512).not.toBe(verified.registryArchiveSha512);
 
       const originalTar = gunzipSync(sourceBytes);