pikelet-wasm 0.7.0 → 0.8.0

package/README.md

@@ -1,589 +1,532 @@
 # Pikelet
 
-Pikelet is a search engine you host like a file.
+**Knowledge that ships as a file.**
 
-> Renamed from **Pancake** (2026-09). Same project, same wire format —
-> existing `.pancake` artifacts and their identities remain valid, and the
-> old package names are deprecated pointers to `pikelet-wasm` and
-> `pikelet`.
+Pikelet compiles a corpus into one self-contained, queryable artifact.
 
-At the bottom there's a small WebAssembly HNSW vector engine that runs
-anywhere JavaScript does — Node, browsers, Cloudflare Workers — with no
-native dependencies. On top of it sit immutable search artifact formats:
-files that package an index, corpus records, query interpretation,
-calibration, and evaluation data, and that can be served from any storage
-that answers byte-range requests.
+A model can interrogate a 456,153-record knowledge base whose backend is a static file.
 
-Where this has been heading is the **complete search artifact**: one
-`.pikelet` file that answers natural-language queries with hydrated,
-confidence-scored results, using nothing but the file, range reads, and a
-reader.
+A `.pikelet` can carry the source text, semantic index, keyword index, query encoder, integrity commitments, retrieval calibration, and evaluation fixtures needed to interrogate that corpus. Put the file on disk, S3, R2, a CDN, or any static HTTP host. A reader can mount it locally or over HTTP Range and search it without a vector database, embedding API, or retrieval server.
 
-```text
-query text
-  -> artifact-carried query interpreter
-  -> vector search over compressed sketch/index data
-     + BM25 over the embedded lexical index, rank-fused
-  -> lazy range reads for records
-  -> calibrated hydrated results
+Requires Node 20+.
+
+```bash
+npx pikelet compile --source ./docs --out docs.pikelet
 ```
 
-The `pikelet-wasm` package carries both the vector engine and the artifact
-runtime.
+```text
+Ingested 3 docs -> 3 chunks
+Embedded 3/3 chunks with inline transformer
+Built complete .pikelet artifact with 24.5 MB
+Compiled docs.pikelet
+  24.5 MB, 3 records, identity 8d731a...
+```
 
-## Knowledge Packs
+First run fetches the ~25 MiB query encoder from a GitHub release and caches it; every `.pikelet` file is at least that size regardless of corpus, because the encoder ships inside it — a 5-file folder and a 500-file folder both start around 25 MiB.
 
-The same file doubles as a **knowledge pack** for LLMs. A `.pikelet` is a
-portable, immutable corpus that contains its own query encoder, semantic
-and lexical indexes, calibrated abstention, provenance, and integrity
-metadata. Publish it as a static file; an MCP client attaches and queries
-it directly over HTTP range requests — no index to rebuild, no vector
-database to run, no embedding service to call:
+Then query it from an LLM — Claude Code, Claude Desktop, or any MCP client:
 
 ```bash
-npx pikelet mcp install --client claude-code \
-  --pack https://github.com/mcn92/pancake/releases/download/artifact-wiki-inline-v4/pancake-wiki-inline.pancake#1b180adf4c6cebb2dcd5615256df6a25dac5fda8738dbbc11d60af86046f97f3
+npx pikelet mcp install --client claude-code --pack ./docs.pikelet
+# or --client claude-desktop; any other MCP client can run
+# `npx pikelet mcp --pack ./docs.pikelet` directly, no install step
+```
+
+```text
+Wrote MCP server "knowledge-packs" to ./.mcp.json
+Claude Code picks it up on the next session in this project.
 ```
 
-Then ask questions. That line pins 456,153 passages of Simple English
-Wikipedia by content hash: the mount transfers a ~52 MiB resident slice
-of the 649 MiB file, each question costs ~127 range reads, results carry
-their provenance (pack identity, title, section, source), and a pack that
-cannot answer says so instead of guessing. Details in the
-pikelet README ("Attaching packs to an LLM") and `packs/`.
-
-## What's in This Repo
-
-Three layers, bottom to top:
-
-1. **WASM vector engine**
-   - In-memory HNSW index with float32 and row-wise affine uint8 backends.
-   - JavaScript API: `Pikelet.create()`, `add()`, `search()`, `export()`,
-     `restore()`.
-   - Source in `src/`, package entrypoints at `pancake.js`,
-     `pancake.node.mjs`, `pancake.web.mjs`.
-
-2. **Search artifacts**
-   - Immutable, integrity-checked files built from indexes and corpus data,
-     range-readable from local files, R2, S3, CDNs — anything that serves
-     byte ranges.
-   - One product format, one index layer beneath it:
-     - `.pikelet`: the complete one-file search artifact — the product.
-     - `.pancake-sketch`: its index segment (resident sketch plus lazy
-       rerank rows), also usable standalone; format 2 (the builder's
-       default) interleaves per-row digests with the rows, so every row a
-       query fetches is verified on that read.
-   - Two adjacent formats that are not search artifacts in the contract
-     sense:
-     - `.pnck`: the engine's snapshot envelope (`export()`/`restore()`
-       serialization), consumed by the compilers and by layer-1 users.
-     - `.pancake-range`: **deprecated** range-readable index profile. The
-       sketch geometry replaced it (5x faster over real networks at a
-       third of the size); readers stay supported for existing artifacts,
-       but no new ones should be built.
-   - Specs: [spec/SEARCH_ARTIFACT_CONTRACT.md](spec/SEARCH_ARTIFACT_CONTRACT.md),
-     [spec/SKETCH_PROFILE.md](spec/SKETCH_PROFILE.md), and
-     [spec/COMPLETE_PROFILE.md](spec/COMPLETE_PROFILE.md).
-
-3. **Products and compilers**
-   - `pikelet/`: the fast path. One command compiles a docs
-     folder or a live site into a complete `.pikelet` file:
-     ```bash
-     npx pikelet compile --source ./docs --out search.pikelet
-     ```
-     or scaffolds a deployable search app:
-     ```bash
-     npx pikelet create --name my-docs-search --source ./docs --no-deploy --yes
-     ```
-   - `examples/05-one-file-search/`: the flagship path — the complete
-     `.pikelet` container, its compilers, and acceptance tests.
-   - `examples/04-static-wiki-pack/`: wiki-scale corpus preparation and the
-     sketch artifact pipeline.
-   - `examples/03-edge-docs-search/`: a Worker search app with a bundled
-     snapshot, distilled query encoder, and calibrated abstention.
-
-## Why Pikelet Exists
-
-Most vector search libraries assume a server process, native binaries, or a
-database service. Pikelet is built for a different deployment shape:
-
-- static files instead of always-on index servers;
-- byte-range reads instead of whole-index downloads;
-- readers for browsers, Workers, and Node;
-- explicit artifact identity and digest verification;
-- query interpretation and evaluation data carried inside the artifact;
-- compact corpus-side vector representations that keep memory and transfer
-  costs sane.
-
-The result is search you can host like an asset instead of operating like a
-database.
-
-## The Flagship: One-File Search
-
-The complete profile (`.pikelet`) packs the five components of a search
-application into one content-addressed file:
+Claude now has a `search` tool over your docs. Or query it directly from code:
+
+```js
+import { openPikeletFile } from 'pikelet-wasm/complete';
+const pack = await openPikeletFile('docs.pikelet');
+const out = await pack.query('how do workers restore snapshots', { k: 5 });
+console.log(out.matchQuality, out.results[0]?.title);
+// 'strong' 'Snapshot restore'
+```
+
+That's the whole loop. `compile` also takes a live URL (`--source https://docs.example.com`) instead of a directory. If you want a deployed search app — a Worker + UI, not a file — use `npx pikelet create` instead; see [`pikelet/README.md`](pikelet/README.md) for the full CLI reference and the tradeoffs between the two. `compile` never needs the scaffold path's `@xenova/transformers` dependency; skip its ~140 MB install with `npm install -g pikelet --omit=optional` if you only need `compile`/`mcp`.
+
+Under the hood, the file is one container for everything a reader needs:
 
 ```text
-index       embedded .pancake-sketch artifact
-corpus      JSON records behind an offsets table
-encoder     query interpreter declaration or inline model data
-calibration abstention / match-quality model
-evaluation  golden queries and expected behavior
-lexical     BM25 inverted index for hybrid retrieval (optional; readers
-            that predate it serve vector-only from the same file)
+documents
+    │
+    ▼
+┌──────────────────┐
+│   docs.pikelet   │
+│                  │
+│ corpus           │
+│ semantic index   │
+│ lexical index    │
+│ query encoder    │
+│ integrity        │
+│ calibration      │
+│ evaluation       │
+└──────────────────┘
+    │
+    ├── local file
+    └── static HTTP / object storage
+              │
+              ▼
+        browser / Node / edge / agent
 ```
 
-The reader verifies the manifest and eager segments, opens the sketch index
-against a range source, and hydrates only the records the final results
-need.
-
-Query interpretation comes in three kinds. Each picks two of
-**self-contained**, **small**, and **teacher-quality**, and gives up the
-third — that trade-off, not history, is why all three exist:
-
-- **kind 3: `inline-transformer-v1`** — self-contained + teacher quality.
-  The artifact carries the WordPiece vocab and quantized MiniLM teacher
-  weights as verified data; the reader ships the execution kernels. Costs
-  ~25 MB of encoder no matter how small the corpus. This is the default:
-  `pikelet compile` builds kind 3.
-- **kind 1: `student-inline-v1`** — self-contained + small. A
-  corpus-distilled student encoder (~1 MiB), pure-JS execution. The only
-  way a small docs corpus compiles to a file measured in single-digit MB;
-  quality is bounded by the distillation.
-- **kind 2: `external-transformers-v1`** — small + teacher quality, but
-  not self-contained: the artifact pins a host-supplied encoder (model id,
-  pooling, normalization, max tokens) and verifies it against embedded
-  test vectors before serving. The escape hatch for encoders too big to
-  inline and hosts that already run one.
-
-Kind 3 is the flagship: the file carries the corpus, index, tokenizer,
-encoder weights, calibration, and evaluation data — the reader supplies
-code, the artifact supplies everything else. Ask it about volcanoes and no
-service, model host, or network dependency is involved beyond range reads
-of the file itself.
+Search is the interface. **The file is the knowledge deployment unit.**
 
-```bash
-cd examples/05-one-file-search
-node compile-wiki.mjs --inline-encoder
-node compile.mjs --inspect pancake-wiki-inline.pancake
-node test-inline.mjs
+---
+
+## The shortest demonstration
+
+A real Pikelet pack contains **456,153 Simple English Wikipedia records** in a **648.5 MiB** artifact.
+
+That file was served by a deliberately dumb HTTP server whose only relevant capability was:
+
+```text
+fs.createReadStream + HTTP Range
 ```
 
-Where the inline wiki artifact currently stands:
+There was no vector database, no search service, no embedding service, no application server that understood the pack, no index process on the server.
+
+The pack was mounted by URL and exposed to a real headless Claude process through MCP. Each invocation was restricted with `--strict-mcp-config` to only:
 
 ```text
-456,153 records
-~649 MiB complete artifact (680,029,254 bytes)
-manifest identity: 1b180adf4c6cebb2dcd5615256df6a25dac5fda8738dbbc11d60af86046f97f3
-recall@10: 95.2% at the recommended rerank (97.0% at C=600), against exact
-  fp32 brute-force ground truth on the 200-query pre-registered eval —
-  98.5% on hand-written natural-language questions, 94.8% on single-title
-  lookups (augmented retrieval: hybrid candidates, distance order)
-serves over HTTP range reads: opens on ~52 MiB of the file, ~127 range
-  requests per query (cluster-ordered row layout + manifest fetch hints)
-natural-language query with no host encoder option, ~110 ms/query end to
-  end locally (the resident scan auto-stages the engine's SIMD kernel at
-  this scale; ~540 ms on the pure-JS scan it falls back to)
+mcp__wiki-pack__search
+mcp__wiki-pack__list_packs
+mcp__wiki-pack__get_record
 ```
 
-Release asset (v4 — recovers the pack's canonical build: k-means
-cluster-ordered rows and the 192-dim 2:1-pooled sketch, where v1–v3
-embedded a 96-dim 4:1 sketch in unpermuted order and measured 82.4%; adds
-the hybrid BM25 lexical segment and a format-2 sketch with per-row read
-verification; earlier versions stay published for older checkouts):
-`https://github.com/mcn92/pancake/releases/download/artifact-wiki-inline-v4/pancake-wiki-inline.pancake`
+No web tool. No filesystem tool. No alternate retrieval tool.
 
-`node test-inline.mjs` downloads that file automatically when it is missing
-locally, verifies the manifest identity, and then runs the acceptance
-checks.
+One of the actual responses:
 
-See [examples/05-one-file-search/README.md](examples/05-one-file-search/README.md)
-for the full one-file walkthrough.
+> **Q: What causes earthquakes?**
+>
+> Earthquakes are caused by the movement of tectonic plates in the Earth's crust. Stress builds up along fault boundaries where plates grind against or ride over one another; when that stress exceeds the friction holding the locked fault in place, it suddenly releases as shock waves (seismic waves) that shake the ground [record 429637].
+>
+> There are three main fault types that can produce quakes — normal, reverse (thrust), and strike-slip — and some quakes have less clear-cut causes, like deep shifts in ancient rock or mine-collapse "tremors" [record 429638].
+>
+> Two related mechanisms compound this:
+>
+> * Subduction, where one plate is forced under another into the mantle, produces the most powerful earthquakes and can trigger tsunamis [record 132833].
+> * More broadly, the slow convection-driven movement of crustal plates over the hot mantle is the underlying driver of quakes, volcanoes, and mountain formation [record 132267].
+>
+> Volcanic eruptions can also cause earthquakes, though these are localized to areas near active volcanoes [record 429637].
 
-## The Design Choice Everything Hangs On
+The model did not just repeat the first search hit. It retrieved multiple records and synthesized them into a sourced answer.
 
-The engine's quantized backend stores corpus vectors as row-wise affine
-uint8:
+Other runs produced:
 
 ```text
-value ~= offset[row] + scale[row] * byte
+Who was the first person on the moon?          → Neil Armstrong          (records 408686, 408684)
+How do volcanoes form?                          → plates + subduction + hotspots
+                                                                          (records 132770, 132765, 132852, 132853)
+How does photosynthesis work?                   → two-phase reaction, cited (5 records: 114219, 114220, 114222, 114223, 269279)
+What is the capital of France?                  → Paris                  (records 454641, 302684)
 ```
 
-That one constraint propagates through the whole system:
+That is the product in one demonstration:
 
-- HNSW search keeps the query as float32 and scores it against compressed
-  corpus rows.
-- Distance kernels fuse dequantization with dot/L2 accumulation.
-- SIMD paths load bytes, widen lanes, apply scale/offset, and accumulate.
-- Graph maintenance uses symmetric node-to-node distances derived from the
-  compressed rows and row statistics.
-- Snapshots serialize compact scale/offset/qdata arrays.
-- Sketch artifacts scan compressed resident rows and fetch only rerank
-  candidates.
-- Range-backed readers keep the large corpus side compressed while queries
-  stay precise and transient.
+> **A model is interrogating a 456,153-record knowledge base whose backend is a static file.**
 
-This is why the engine work and the artifact work belong in one project:
-the same corpus-side representation serves in-memory search, serialized
-snapshots, resident sketches, range reads, and reranking.
+The model may already contain some of these facts in its pretrained parameters. This test demonstrates the retrieval, synthesis, citation, and deployment path; the Veyra ablation below tests whether support changes when evidence is removed from the pack.
 
-## Install
+**Network cost.** In a single persistent session (one mount, five queries, one repeat):
 
-From npm:
+| Operation                       | Bytes transferred | Requests |
+| ------------------------------- | ----------------: | -------: |
+| Initial mount                   |          51.7 MiB |       11 |
+| Query 1 + one-time encoder load |          25.9 MiB |       77 |
+| Query 2                         |         504.4 KiB |       37 |
+| Query 3                         |         499.4 KiB |       46 |
+| Query 4                         |         968.9 KiB |       75 |
+| Query 5                         |           1.1 MiB |      116 |
+| Repeated query 1                |         238.4 KiB |        4 |
+| **Total**                       |      **80.8 MiB** |  **366** |
 
-```bash
-npm install pancake-wasm
+Roughly **12.5% of the 648.5 MiB artifact** crossed the wire across that whole session. Excluding the one-time ~25 MiB encoder load, fresh-query traffic ran **~0.5–1.1 MiB per query**. The complete artifact was never downloaded.
+
+The headless-Claude test above used a fresh process per question, so each invocation repaid the ~52 MiB mount and ~25 MiB encoder cost — about 78 MiB per cold query. That's a real operational distinction: **persistent sessions amortize mount and encoder cost; independent cold processes do not.**
+
+*(The large benchmark fixture still carries its historical `.pancake` filename from before the Pikelet rename; current artifacts use `.pikelet`.)*
+
+---
+
+## What happens if the answer is changed or removed from the file?
+
+This is different from asking whether search returns sensible documents. To test whether Pikelet's retrieval-quality signal could form a useful evidence boundary, a synthetic corpus called **Station Veyra Registry** was built. One version contained the fact:
+
+```text
+The Tovash project is housed in Chamber 17.
 ```
 
-From a checkout:
+A second pack was byte-for-byte identical except that the record containing that fact was removed.
 
-```bash
-git clone https://github.com/mcn92/pancake.git
-cd pancake
-npm install
+```text
+full pack:     matchQuality: strong    confidence: 0.915   → Chamber 17
+ablated pack:  matchQuality: none      confidence: 0.136   → unsupported
 ```
 
-The checkout includes prebuilt WASM in `dist/`, so you don't need to
-rebuild the engine unless you edit `src/`.
+After the model had already seen the answer, it was queried against the ablated pack with prompts like "Confirm Tovash is in Chamber 17" and "Tovash project Chamber 17 location." The retrieval result stayed unsupported and the model declined to confirm the location from the pack. A separate, informal session then probed a fresh isolated agent with neutral prompts, leading prompts, authority pressure, invitations to use general knowledge, cross-record distractors, and repeated pressure — six adversarial framings — and it continued distinguishing supported facts from the removed one in every case; that session wasn't captured as a script, so treat it as a described observation rather than a reproducible result.
 
-## Runtime Entry Points
+This does **not** mean Pikelet can prevent an LLM from hallucinating. It means the artifact can expose an explicit evidence boundary that a consuming model can choose to respect — and removing evidence from the artifact changed what that model was able to support from the mounted source.
 
-Published package:
+A second intervention changed only the Tovash location source record from **Chamber 17** to **Chamber 43**, rebuilt the pack, and repeated the same prompt in a fresh session:
 
-```js
-// Node.js CJS
-const Pikelet = require('pikelet-wasm');
+```text
+chamber43 pack: matchQuality: strong    confidence: 0.916   → Chamber 43
+```
 
-// Node.js ESM
-import Pikelet from 'pikelet-wasm';
+The model answered **Chamber 43** and cited the same logical source record. With Veyra not mounted at all, the same prompt produced no chamber number and the model declined to guess. Change the evidence and the grounded answer changes with it; remove the evidence source and the answer disappears.
 
-// Explicit Node/browser entries
-import Pikelet from 'pikelet-wasm/node';
-import Pikelet from 'pikelet-wasm/web';
+The test is synthetic and intentionally narrow. All three packs and the `matchQuality`/`confidence` numbers above are reproducible: `node examples/05-one-file-search/web/public/reproduce-ablation.mjs`. The retrieval side is scripted; the paired LLM-session claims (declining to confirm the removed fact, answering Chamber 43, declining without the pack mounted) were run separately and aren't reproduced by that script.
 
-// Search Artifact layer (sketch readers/builders; the deprecated
-// .pancake-range reader stays exported for existing artifacts)
-import { PancakeSketchArtifact, buildSketchArtifact } from 'pikelet-wasm/artifact';
+---
 
-// Complete one-file profile: reader (any runtime) and builder (Node)
-import { openPikeletFile } from 'pikelet-wasm/complete';
-import { assemblePancakeFile } from 'pikelet-wasm/complete/builder';
-```
+## What does the compression cost?
 
-Repository checkout:
+The artifact architecture is only useful if the compact representation does not quietly destroy retrieval. The retrieval path was decomposed on BEIR rather than evaluated only end-to-end, across four configurations that isolate each transformation:
 
-```js
-const Pikelet = require('./pancake.js');
-import Pikelet from './pancake.node.mjs';
-import Pikelet from './pancake.web.mjs';
+```text
+A  upstream all-MiniLM-L6-v2, float32 corpus, exhaustive search
+B  Pikelet embedded encoder,  float32 corpus, exhaustive search
+C  Pikelet embedded encoder,  affine-u8 corpus, exhaustive search
+D  Pikelet embedded encoder,  affine-u8 corpus, Pikelet HNSW
 ```
 
-The browser entry expects the runtime or bundler to resolve
-`dist/engine.wasm`.
+Corpus mapping and evaluation config were frozen before the runs. Official BEIR qrels are used; no LLM judges relevance.
 
-## Engine Quick Start
+| Dataset  | Config                                     |    nDCG@10 |  Recall@10 | Recall@100 | median ms/q | p95 ms/q |
+| -------- | ------------------------------------------ | ---------: | ---------: | ---------: | ----------: | -------: |
+| SciFact  | A — upstream float exhaustive              |     0.6451 |     0.7833 |     0.9250 |         3.6 |      4.0 |
+| SciFact  | B — Pikelet encoder / float exhaustive     |     0.6512 |     0.7942 |     0.9417 |         3.8 |      4.4 |
+| SciFact  | C — Pikelet encoder / affine-u8 exhaustive |     0.6500 |     0.7942 |     0.9417 |         6.9 |      8.7 |
+| SciFact  | D — Pikelet encoder / affine-u8 HNSW       | **0.6500** | **0.7942** | **0.9417** |    **0.15** | **0.24** |
+| NFCorpus | A — upstream float exhaustive              |     0.3159 |     0.1550 |     0.3115 |         2.6 |      3.1 |
+| NFCorpus | B — Pikelet encoder / float exhaustive     |     0.3154 |     0.1511 |     0.3044 |         2.8 |      3.3 |
+| NFCorpus | C — Pikelet encoder / affine-u8 exhaustive |     0.3154 |     0.1511 |     0.3036 |         2.9 |      3.6 |
+| NFCorpus | D — Pikelet encoder / affine-u8 HNSW       | **0.3135** | **0.1482** | **0.3061** |    **0.16** | **0.25** |
+| ArguAna  | A — upstream float exhaustive              |     0.3698 |     0.7653 |     0.9772 |         7.8 |     10.8 |
+| ArguAna  | B — Pikelet encoder / float exhaustive     |     0.3506 |     0.7397 |     0.9801 |         6.1 |      7.3 |
+| ArguAna  | C — Pikelet encoder / affine-u8 exhaustive |     0.3496 |     0.7368 |     0.9801 |         6.4 |      7.5 |
+| ArguAna  | D — Pikelet encoder / affine-u8 HNSW       | **0.3496** | **0.7368** | **0.9808** |    **0.12** | **0.20** |
 
-Use the core engine when you already have vectors and want an in-memory ANN
-index.
+These results are more useful because they are not uniformly flattering.
 
-```js
-import Pikelet from 'pikelet-wasm';
+**Affine-u8 storage is not the main quality cost** (B→C nDCG@10: SciFact 0.6512→0.6500, NFCorpus 0.3154→0.3154, ArguAna 0.3506→0.3496). **HNSW is similarly close to exhaustive search** at these settings (C→D: SciFact and ArguAna unchanged at reported precision; NFCorpus exposes a small approximation loss, 0.3154→0.3135).
 
-const index = await Pikelet.create({
-  dim: 384,
-  maxElements: 100000,
-  metric: 'cosine',
-  quantized: true,
-});
+**The largest observed loss is the embedded query encoder on ArguAna**: A→B moves nDCG@10 from 0.3698 to 0.3506, about a 5% relative reduction. Recall@100 actually improves slightly (0.9772→0.9801) — the relevant document is generally still in the candidate set; the degradation is in fine ordering near the top. That limitation isn't hidden: MiniLM is small *because* the goal is to fit the query encoder inside the artifact. It is not state of the art, and the compact implementation is not behaviorally identical to an upstream sentence-transformers runtime on every task.
 
-const docVector = new Float32Array(384).fill(0.1);   // your embedding here
-const queryVector = new Float32Array(384).fill(0.1); // your query embedding here
+The benchmark harness, quantization-conformance test, frozen configuration, and raw runs live under `bench/beir/`.
 
-const id = index.add(docVector);
+---
 
-const results = index.search(queryVector, 10);
-// [{ id: 0, distance: 0.12 }, ...]
+## Why make knowledge a file?
 
-index.delete(id);
-index.compact();
+The conventional retrieval deployment looks something like:
 
-const snapshot = index.export();
-const restored = await Pikelet.restore(snapshot, { maxElements: 100000 });
+```text
+documents → chunking → embedding service → vector database
+                                          → keyword database
+                                          → retrieval service → application API → agent
+```
+
+That is the correct architecture for many workloads. But it is a lot of machinery when the corpus is fundamentally a release artifact: product documentation, a manual, a source tree, a legal code, a standards corpus, a research collection, a book, a knowledge snapshot, an offline reference set. These datasets often change daily, weekly, monthly, or with releases — not hundreds of times per second.
+
+For those workloads, Pikelet asks a different question:
 
-index.dispose();
-restored.dispose();
+> **What if retrieval could be compiled ahead of time and distributed with the corpus?**
+
+Then deployment becomes: copy the file, cache it, pin it, put it behind a CDN, mount it by URL. The storage layer does not need to know that the file contains vectors.
+
+It is not a replacement for a mutable vector database. It is an attempt to make **static and slowly changing knowledge deploy like any other artifact**.
+
+---
+
+## Attach a pack to an LLM
+
+`pikelet mcp` exposes one or more packs through the Model Context Protocol:
+
+```bash
+npx pikelet mcp install \
+  --client claude-code \
+  --pack https://example.com/docs.pikelet#<sha256>
 ```
 
-If you have records with vectors:
+The agent gets `search`, `get_record`, `list_packs`, `verify_pack`. A search result carries the identity of the pack and the location of the source record, so an agent can work against `product-docs.pikelet`, `rust-reference.pikelet`, `policy-2026-09.pikelet`, `customer-manual-v4.pikelet` without each publisher operating a retrieval API. The artifact can be local, private, public, behind authenticated object storage, or distributed like any other static asset.
 
-```js
-const rows = [
-  { id: 'doc-1', vector: embedding1 },
-  { id: 'doc-2', vector: embedding2 },
-];
-
-const { index, idMap } = await Pikelet.fromVectors(rows, {
-  metric: 'cosine',
-  quantized: true,
-});
-
-const hits = index.search(queryEmbedding, 5);
-console.log(idMap.get(hits[0].id));
+A pack mounted with a content hash has a stable identity — `https://example.com/docs.pikelet#8d731...` — so "what body of knowledge did this agent query?" has a reproducible answer.
+
+**A mounted pack's content reaches the model as tool output.** `verify_pack` proves the bytes are intact and match their pinned identity; it does not prove the corpus itself is trustworthy. Mounting a pack from a source you don't control is the same trust decision as giving an agent any other untrusted-content tool — treat pack text the way you'd treat search results or fetched web pages, not as instructions.
+
+**Try it with your own questions.** The three Veyra packs from the ablation test above (`examples/05-one-file-search/web/public/veyra*.pikelet`) are committed to this repo, so there's a working MCP mount you can query with anything, not just the fixed prompts above:
+
+```bash
+claude -p "your question here" \
+  --mcp-config examples/05-one-file-search/web/public/veyra.mcp.json \
+  --strict-mcp-config \
+  --allowedTools "mcp__veyra-demo__search,mcp__veyra-demo__list_packs,mcp__veyra-demo__get_record"
 ```
 
-On Node entrypoints, file helpers are available:
+or drop the flags and just run `claude` from the repo root — Claude Code picks up project-level `.mcp.json` configs automatically, so pointing one at this file (or copying its `veyra-demo` server into your own) gets the same three packs into an interactive session. All three packs share the same 94-ish-record synthetic corpus, so the interesting thing to ask about is Tovash's chamber — the full and Chamber 43 packs will disagree with each other, and the ablated pack won't answer at all.
 
-```js
-const { index, idMap } = await Pikelet.loadJsonFile('vectors.jsonl', {
-  metric: 'cosine',
-  vectorKey: 'embedding',
-  idKey: 'docId',
-  maxFileBytes: 64 * 1024 * 1024,
-});
-
-const restored = await Pikelet.loadSnapshotFile('index.pnck', {
-  dim: 384,
-  maxElements: 100000,
-  metric: 'cosine',
-  quantized: true,
-});
+---
+
+## How a remote query runs
+
+Over a network, what makes search slow is not bytes; it's sequential round trips. Graph traversal is a chain of dependent reads — fetch node, inspect neighbors, fetch the next node, repeat — and across object storage those dependent round trips dominate. Measured against SIFT1M over real network storage, a resident scan plus one batched candidate-fetch phase beat graph traversal by about 5× at equal recall. So the remote artifact path carries no graph. The HNSW graph still exists — it's the in-memory engine, used when the whole index is local and round trips are free; that's the path BEIR Config D measures.
+
+For the remote path:
+
+1. **Resident tier** — a pooled sketch of every semantic row loads once when the artifact opens and stays in memory. For the 456,153-record Wikipedia pack: 648.5 MiB artifact, 51.7 MiB mount fetch. A SIMD kernel scans all of it in milliseconds.
+2. **Candidate selection** — the scan picks the top `C` candidates against the query vector; the lexical BM25 index can contribute additional candidates into the same set. `C` is the only real knob: the compiler measures recall against brute force on held-out queries at build time and writes the operating point into the file, so readers don't have to guess it.
+3. **Batched byte-range fetch** — full affine-u8 rows for the candidate set are fetched in one parallel round, nearby ranges coalesced, rather than a graph-dependent network walk.
+4. **Full rerank** — fetched rows are scored against the float query and verified against their digest.
+5. **Corpus hydration** — only the records needed for returned results are fetched, each carrying record ID, title, section, source, and artifact identity. The reader returns evidence, not anonymous vector IDs.
+
+That architecture is why a 648.5 MiB pack can answer a fresh query while fetching about 0.5–1.1 MiB after warmup.
+
+---
+
+## Integrity is part of the read path
+
+A range-readable artifact cannot hash the entire file on every open without defeating the point of range reads, so integrity is layered: the resident structural portion is verified during open; lazily fetched index rows and corpus records carry independent commitments and are checked when read. Bytes a query never touches don't have to cross the network merely to prove the bytes it *did* use were correct.
+
+One exception: a lexical (BM25) segment above 8 MiB opens lazily and is covered only by the manifest's whole-segment digest, not per-read like index rows and corpus records — the same transitional stance format-1 sketch rows carry. A pack large enough for this to apply can have its lexical candidates altered between open and a full verification pass without failing a query.
+
+The failure-mode suite (`bench/range-proof/failure-modes.mjs`) exercises the important cases:
+
+```text
+correct Range server         → mounts, queries successfully
+server ignores Range         → small files fall back to a bounded download;
+                                large files refuse ("host ignores Range and the
+                                file is 680029254 bytes; refusing full download" —
+                                the cap is currently 64 MiB)
+bytes change under a pinned identity → refused; tampered data is not silently served
+truncated Range response     → fetch fails; no partial result is silently
+                                interpreted as valid data
 ```
 
-## Complete Artifact Quick Start
+The point is not that static HTTP is magically reliable. The point is that a static artifact can fail in explicit, testable ways.
 
-Use the complete reader when you want a file that is itself the search
-application data plane. To build one from your own docs, see the compile
-command above (`npx pikelet compile`).
+---
 
-```js
-import { openPikeletFile } from 'pikelet-wasm/complete'; // or './complete/index.mjs' in a checkout
+## Match quality and abstention
+
+A nearest neighbour is not automatically evidence that a corpus answers a question. Pikelet can calibrate retrieval signals at build time (best semantic distance, distance margin, lexical coverage, retrieval agreement). When the corpus supports a reliable classifier, results carry `matchQuality: strong | weak | none`. When calibration can't separate supported from unsupported reliably — a single novel may be semantically homogeneous enough that the fit isn't trustworthy — Pikelet reports `matchQuality: unscored` and records why calibration was skipped, rather than manufacturing confidence. A `none` verdict withholds `results` by default; pass `query(text, { showAbstained: true })` to see the raw retrieval anyway — `matchQuality` and `confidence` are unaffected either way.
 
-const search = await openPikeletFile('examples/05-one-file-search/pancake-docs.pancake');
+`matchQuality` is evidence about retrieval support. It is **not** a guarantee that an LLM will never hallucinate.
 
-const out = await search.query('how do workers restore snapshots', { k: 5 });
+---
 
-console.log(out.matchQuality, out.confidence);
-console.log(out.results[0].title);
+## What's inside a `.pikelet`
 
-await search.close();
+```text
+manifest        format versions, segment offsets, artifact identity
+semantic index  resident sketch rows, full affine-u8 rows, row commitments
+corpus          source records, offsets, per-record commitments
+query encoder   WordPiece vocabulary, quantized MiniLM weights, encoder declaration
+lexical index   BM25 postings
+calibration     supported / unsupported retrieval model
+evaluation      golden queries / expected behavior
 ```
 
-For kind-3 artifacts, no host encoder is needed:
+The artifact is immutable. Publish a new corpus by publishing a new artifact; old artifacts retain their identity.
 
-```js
-const search = await openPikeletFile('pancake-wiki-inline.pancake');
-const out = await search.query('how do volcanoes form', { k: 5 });
+**Encoder profiles.** Self-containment has a cost — the default profile carries ~25 MiB of MiniLM data regardless of corpus size. Three arrangements: **inline** (tokenizer + weights + runtime in the artifact — largest file, no external dependency, used by the Wikipedia demo above), **distilled/compact** (smaller corpus-specific representation, lower footprint, potentially lower quality), **host-supplied** (the artifact declares expected encoder behavior and verifies the host implementation against embedded test vectors — smallest artifact, no longer fully self-contained). The format treats the encoder as a capability, not Pikelet's identity — MiniLM is the current choice, not a permanent requirement.
+
+---
+
+## One decision
+
+Most of the implementation follows from how a vector is stored. Each row is 8-bit integers plus two floats:
+
+```text
+x[d] ≈ offset + scale · q[d]        q[d] ∈ 0..255
 ```
 
-For kind-2 artifacts, pass `options.encodeQuery`; the reader runs it
-against the declaration's verification vectors before serving and refuses
-the open if they disagree (`info().encoderVerified` reports the outcome).
+That's a per-row affine map. It costs 4× less memory than float32, which is the ordinary reason to do it. The reason it runs through the whole project is that every operation search needs — dot products, sums, averages — is linear, and affine terms factor out of linear operations.
 
-The reader also accepts a range source, which is how a `.pikelet` on R2 or
-a CDN gets queried without downloading it:
+**Query against a stored row.** The query stays float32 and is never quantized.
 
-```js
-const search = await openPikeletFile({
-  size,
-  async read(offset, length) {
-    // return bytes for [offset, offset + length)
-  },
-});
+```text
+y·x = offset·Σy + scale·(y·q)
 ```
 
-On integrity: every artifact-derived read is bounds-checked and budgeted
-(`maxReadBytes`, `maxRecordBytes`). Format-2 files (`pancake-complete-v2`,
-the builder's default) verify each hydrated record against a per-record
-digest on its own range read (`info().corpusIntegrity`), and an embedded
-format-2 sketch verifies each lazily fetched index row the same way
-(`info().indexRowIntegrity`) — so a tampered transport fails the query
-instead of skewing its results. Older files with a format-1 sketch commit
-the lazy index rows to the identity but don't verify them per read; for
-those, pass `verifyIndexVectors: true` (or call `verifyVectors()`) to
-authenticate them in one full pass before trusting results from an
-untrusted transport (spec/COMPLETE_PROFILE.md section 6).
-
-### Attaching packs to an LLM
-
-A complete artifact doubles as a portable knowledge pack: everything an
-LLM needs to query a body of knowledge — corpus, indexes, encoder,
-calibrated abstention, integrity commitments — in one immutable,
-identity-pinned file. `pikelet mcp` serves packs over the
-Model Context Protocol so Claude Code, Claude Desktop, or any agent
-framework can attach them as a retrieval tool with one config line — no
-vector database, no embedding service, no retrieval backend. Results
-carry full provenance (pack, manifest identity, title, heading path,
-source), and a pack that cannot answer says so instead of returning
-plausible noise. See the pikelet README's
-"Attaching packs to an LLM (MCP)" section.
-
-## Demos
-
-Start with [DEMOS.md](DEMOS.md) for the maintained demo path.
-
-Useful commands:
+The inner loop multiplies floats by bytes. The two constants come in once at the end. No decompressed copy of the row ever exists.
 
-```bash
-npm run demo                  # synthetic engine validation
-npm run demo:artifact         # range artifact search
-npm run demo:sketch           # sketch artifact search/rerank path
-npm run test:browser          # browser smoke test
-node examples/05-one-file-search/test-file.mjs
-node examples/05-one-file-search/test-wiki.mjs
-node examples/05-one-file-search/test-inline.mjs
+**Stored row against stored row.** This is what graph construction needs, thousands of times per insert.
+
+```text
+x_i·x_j = D·o_i·o_j + o_i·s_j·Σq_j + o_j·s_i·Σq_i + s_i·s_j·(q_i·q_j)
 ```
 
-The one-file example is the closest thing to the project's current center
-of gravity:
+`D` is the vector's dimensionality (384 for the bundled encoder). `q_i·q_j` is an integer dot over two byte arrays, which maps efficiently onto SIMD. `Σq` is stored per row. The HNSW graph is built and repaired entirely on compressed data.
+
+**Pooling.** Average adjacent groups of `p` bytes and you get a shorter row. Because the mean of `offset + scale·q` over a group equals `offset + scale·mean(q)`, the shorter row keeps the *same two constants*. That's the resident sketch tier; a micro tier is the same thing done twice.
+
+**Weights.** The bundled query encoder is a 6-layer MiniLM whose matrices are stored the same way, one (scale, offset) per 64-column block. Activations stay float32, weights stay bytes, dequantization happens inside the matmul — the same widen-and-multiply trick, a separate kernel, that scores vectors.
+
+The consequence for the file format: a row decodes from its own bytes and its own two floats and nothing else. No codebook, no global statistics. Every row is a fixed-size byte range at a computable offset — locatable by arithmetic, fetchable on its own, hashable on its own, verifiable on the read that fetches it.
+
+**Why not product quantization.** Product quantization would compress harder. It would also need a codebook, a training pass, table lookups in the distance kernel, and rows that mean nothing without the codebook. Four-to-one with no shared state was the better trade for a file meant to be read in pieces.
+
+---
+
+## Build once, publish anywhere
 
 ```bash
-cd examples/05-one-file-search
-node compile.mjs
-node test-file.mjs
-node serve.mjs
+npx pikelet compile --source ./docs --out docs.pikelet
 ```
 
-## API Snapshot
+```js
+import { openPikeletFile } from 'pikelet-wasm/complete';
 
-Core index:
+const pack = await openPikeletFile('https://example.com/docs.pikelet#<sha256>');
+const result = await pack.query('how do workers restore snapshots', { k: 5 });
 
-```js
-const index = await Pikelet.create(options);
-index.add(vector);
-index.addBatch(vectors);
-index.search(query, k, options?);
-index.searchFiltered(query, k, allowedIds, options?); // allowedIds: Set of ids
-index.delete(id);
-index.compact();
-index.export();
-index.dispose();
+console.log(result.matchQuality);
+for (const hit of result.results) console.log(hit.title, hit.section);
+
+await pack.close();
 ```
 
-Common options:
+The same artifact can also be opened from a local path or any custom source implementing `{ size, read(offset, length) }`.
+
+**Or use the search engine directly**, if you already have vectors and don't need the artifact layer:
 
 ```js
-{
-  dim: 384,
-  maxElements: 100000,
-  metric: 'cosine',       // 'cosine' or 'l2'
-  quantized: true,
-  M: 12,
-  efConstruction: 75,
-  efSearch: 100,
-  seed: 108
-}
+import Pikelet from 'pikelet-wasm';
+
+const index = await Pikelet.create({ dim: 384, maxElements: 100000, metric: 'cosine', quantized: true });
+index.add(vector);
+const results = index.search(query, 10);
+const snapshot = index.export();
 ```
 
-Snapshot helpers:
+float32 HNSW, affine-u8 HNSW, insert/delete, compaction, import/export, deterministic snapshots, WASM with no native addon dependency. Pikelet is usable as a vector engine — that's just no longer the main reason the project exists.
 
-```js
-await Pikelet.restore(bytes, options);
-await Pikelet.loadSnapshotFile(path, options);
-await Pikelet.loadJsonFile(path, options);
-await Pikelet.fromVectors(rows, options);
-```
+---
 
-Range and sketch artifact APIs ship at `pikelet-wasm/artifact`; the
-complete-profile reader and builder ship at `pikelet-wasm/complete` and
-`pikelet-wasm/complete/builder`. The wiki-scale compilers and acceptance
-tests live in `examples/05-one-file-search/`.
+## What this is not
 
-## Building From Source
+**Not a claim that vector databases are obsolete.** If your corpus changes continuously, needs transactional updates, serves many tenants, or already lives comfortably in a database, use a database. Pikelet targets `build → publish → query many times → replace on release`.
 
-You only need this if you change the C++ engine under `src/`.
+**Not state-of-the-art embedding research.** The bundled model is MiniLM-L6, chosen for being small enough to live inside the artifact. ArguAna demonstrates a real quality cost from the compact encoder.
 
-Requirements:
+**Not "LLMs can no longer hallucinate."** The artifact exposes retrieved evidence, provenance, integrity, and an explicit support signal. Whether an agent obeys those signals is an agent behavior question.
 
-- Node.js
-- Emscripten SDK
+**Not a new HNSW algorithm.** HNSW is HNSW. HTTP Range is HTTP Range. BM25 is BM25. MiniLM is MiniLM. Affine quantization is not new either. The project is about what becomes possible when those pieces are arranged around one constraint: **the knowledge base itself must be distributable as a file and remain useful without dedicated retrieval infrastructure.**
 
-Build:
+---
 
-```bash
-npm run build
-```
+## Why the file format matters
 
-Build scalar and SIMD variants:
+A retrieval service is identified by an endpoint. A Pikelet is identified by its contents.
 
-```bash
-npm run build:all
-```
+- **Reproducibility** — pack hash + record ID identifies the exact evidence a model retrieved.
+- **Versioning** — different releases are different artifacts (`docs-v1.pikelet`, `docs-v2.pikelet`); no silent mutation.
+- **Distribution** — a pack can be mirrored by infrastructure that knows nothing about semantic search.
+- **Offline use** — once local, no network or embedding service needed.
+- **Customer-controlled knowledge** — hand someone the artifact instead of granting access to internal retrieval infrastructure.
+- **Agent knowledge environments** — run a task against a frozen snapshot, reproduce it later against the same bytes.
 
-The build emits `dist/engine.js`, `dist/engine.wasm`, and scalar variants.
+> **Can knowledge become a first-class software artifact rather than something that always has to live behind a service?**
 
-## Tests
+---
 
-Core (`npm test` also runs the artifact and complete-profile conformance
-suites):
+## When Pikelet is a good fit — and when it isn't
 
-```bash
-npm test
-npm run test:fuzz
-npm run test:simd
-npm run test:browser
-npm run test:scaffold
-```
+**Use it when:**
 
-Complete profile, end to end:
+- your corpus is static or changes on a release cycle
+- you want semantic search without operating search infrastructure
+- you want search inside a browser, Node process, edge worker, Electron app, or offline tool
+- you want to distribute a searchable corpus to someone else
+- you want an LLM agent to query a frozen, versioned body of knowledge
+- static/object storage is easier to deploy than a database
+- provenance and reproducibility matter
+- a content-addressed knowledge snapshot is useful
 
-```bash
-node examples/05-one-file-search/test-file.mjs
-node examples/05-one-file-search/test-wiki.mjs
-node examples/05-one-file-search/test-inline.mjs
-```
+Examples: documentation, SDK/API references, technical manuals, research corpora, standards, legal texts, books, product knowledge, code/documentation snapshots, evaluation corpora, agent reference packs.
 
-The inline wiki acceptance test downloads the large release artifact on
-demand when `examples/05-one-file-search/pancake-wiki-inline.pancake` is
-missing.
+**Don't use it if:**
 
-## Performance Notes
+- your corpus has heavy online writes
+- you need transactional mutation
+- you need a multi-tenant authoritative search service
+- you need exact nearest-neighbour search at very large scale
+- your corpus is so large that a linear resident sketch scan is inappropriate
+- you already operate a vector database happily and portability buys you nothing
 
-Performance is workload-dependent, but these are the knobs that matter:
+The resident remote scan is linear in row count. The current architecture targets corpora through the low millions of records, not arbitrary web scale.
 
-- `quantized: true` for much smaller corpus-side vector storage.
-- `efSearch` for the recall/latency tradeoff.
-- sketch artifacts for depth-1 candidate selection before lazy rerank
-  reads.
-- corpus layout and clustering for fewer remote read rounds.
-- kind-3 inline encoders when deployment shouldn't depend on an external
-  ML runtime.
+---
 
-The older engine-level benchmarks are still useful for HNSW behavior. The
-newer artifact-level benchmarks are more representative of what the project
-is actually for: search from static files and range-readable storage.
+## Repository map
 
-The native baselines the engine benchmarks compare against (faiss-node,
-hnswlib-node, usearch) are not dependencies of `pikelet-wasm`; install
-them on demand with `cd benchmarks && npm install` before running those
-scripts. See `benchmarks/`, `benchmark_results/`, and the example READMEs
-for current numbers.
+```text
+src/                              C++/WASM vector engine: HNSW, float32 and
+                                   affine-u8 backends, mutation, compaction,
+                                   snapshot import/export
+complete/, pikelet-artifact.js    Readers and builders for the complete
+                                   range-readable artifact
+pikelet/                          CLI, compiler, MCP server, encoder
+                                   integration, higher-level tooling
+spec/                             Byte-level artifact contracts
+bench/beir/                       Frozen BEIR ablation harness (encoder,
+                                   quantization, HNSW quality)
+bench/range-proof/                The deliberately boring static-HTTP proof:
+                                   dumb-server.mjs, proof.mjs, mcp-proof.mjs,
+                                   llm-proof.mjs, failure-modes.mjs
+examples/05-one-file-search/      Large single-artifact search and embedded
+                                   encoder work
+examples/06-mcp-knowledge-pack/   Compile, mount, search, and hydrate
+                                   records through MCP
+packs/                            Pack hosting and distribution examples
+```
 
-## Tradeoffs
+---
 
-Pikelet is a good fit when:
+## Reproduce the proofs
 
-- you want search in JavaScript runtimes without native addons;
-- you want static-file or edge deployment;
-- you need reproducible, inspectable search artifacts;
-- your corpus can be built offline;
-- byte-range reads are cheaper than operating a dedicated search service.
+**Range proof** (`bench/range-proof/`) is built around a server that does not understand Pikelet. It checks: static HTTP + Range + Pikelet client = remote semantic retrieval, without a full download. The main script reports artifact size, records, mount bytes/requests, per-query bytes/requests, cache behavior. `failure-modes.mjs` independently exercises Range supported / ignored / tampered bytes / truncated response. `mcp-proof.mjs` and `llm-proof.mjs` use a real MCP client and a real headless Claude process rather than a mocked model response.
 
-It's the wrong tool when:
+**BEIR evaluation** (`bench/beir/`) keeps stages separate so a quality change can be attributed to the component that caused it, plus a standalone conformance fixture checking the JS benchmark path against the actual C++ affine-u8 representation. Don't read the latency columns as a universal native-performance comparison — they measure the benchmark paths under the stated harness. The quality deltas are the important part.
 
-- you need high-rate online mutation;
-- you need a multi-tenant database server;
-- you require exact nearest-neighbor search at large scale;
-- your deployment can already use a mature native ANN service with no
-  portability constraints.
+---
 
 ## Status
 
-The engine and the artifact readers/builders are published and usable
-today (`pikelet-wasm`, with `pikelet` as the app scaffold).
-The complete `.pikelet` profile's spec is still marked draft — Draft 2,
-under review, not frozen — but its reader and builder ship in the package,
-and it is the clearest expression of where the project is going: a search
-engine packaged as one verified, range-readable file.
+Pikelet is early. The implementation is real; the format is not frozen. One primary author. Draft 2 artifact format.
+
+- prebuilt WASM included
+- local and HTTP readers
+- affine-u8 and float HNSW backends
+- embedded query encoder
+- BM25 hybrid retrieval
+- content identity and lazy-read integrity verification
+- calibration/abstention support
+- MCP mounting
+- BEIR retrieval evaluation
+- range-read and failure-mode tests
+- a large 456k-record example artifact
+
+`npm test` exercises the engine, artifact profiles, MCP, ingestion, format hardening, and related conformance suites.
+
+The project was renamed from **Pancake** to **Pikelet** in September 2026; some old fixture filenames and compatibility identifiers still use the previous name. `pancake-wasm` and `create-pancake-search` are deprecated compatibility pointers to the Pikelet packages. Pikelet is unrelated to the pre-existing Pikelet programming language.
+
+---
+
+## The experiment
+
+> **For static and slowly changing corpora, useful semantic retrieval can be compiled into the artifact being distributed instead of operated as a separate service.**
+
+The implementation currently demonstrates: one file, 456,153 records, 648.5 MiB, embedded query encoder, semantic + lexical retrieval, content identity, per-record integrity, MCP mounting, static HTTP hosting, ~0.5–1.1 MiB fresh-query range traffic after warmup, real multi-record LLM synthesis, no retrieval backend.
+
+There are many reasons a database remains the right answer. Pikelet exists for the cases where the knowledge itself should be something you can **build, hash, copy, cache, publish, mount, query, and keep.**
 
 ## License