dsh-kb 0.1.0__tar.gz

dsh_kb-0.1.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-10-25
+
+First public version. Written against a real deployment: a Markdown bundle on
+a network share, mirrored to a Linux host and searched by an AI agent.
+
+### Added
+
+- **Bundle layout** with privacy zones (`z0-public`, `z1-restricted`,
+  `z2-sensitive`), a layout area (`_meta`, `_incoming`) and a root index.
+- **Local mirror** with a manifest-driven incremental sync: a file whose size
+  and mtime are unchanged is never transferred. Opt-in `--prune`.
+- **Local full-text index** on SQLite FTS5: CJK bigram expansion plus the
+  original text, a contentless FTS table with a separate `meta` table, and a
+  `fts5vocab` table used for selectivity.
+- **Two-stage search**: strict `AND` for precision, relaxing to a selective
+  `OR` only when the strict pass is empty.
+- **Zone policy compiled into code**, enforced at three points: mirroring,
+  indexing and querying. Sensitive zones are not even copied to disk.
+- **Read sources**: a filesystem view (local directory, Samba/CIFS or NFS
+  mount, Windows drive or UNC path) and a dependency-free generic WebDAV client
+  (optional Basic auth and mutual TLS, with connect-host/SNI separation for
+  appliances whose certificate CN differs from their address).
+- **Unmounted SMB** (`source=smb`) through `smbclient`, for hosts where mounting
+  needs root or a mount has gone stale. Parses the real `recurse ON; ls` output
+  (verified against a live server, including names with spaces and the trailing
+  `blocks of size …` line).
+- **Network-mount awareness**: `/proc/mounts` inspection picks the real
+  filesystem rather than its `autofs` trigger, reports `rw`/`ro`, and turns
+  `ESTALE` / `EACCES` / `ENOENT` into actionable sentences. `sync --full` covers
+  the one-second timestamp granularity of network shares.
+- **CLI** (`dsh-kb status|doctor|sync|index|refresh|search|read|push|mcp`) with
+  `--json` output, offline operation for everything except `sync`/`push`/
+  `doctor`, best-effort auto-refresh before a search, and a three-level
+  `doctor` report (`ok` / `~~` warning / `!!` failure).
+- **MCP server** (`dsh-kb mcp`): newline-delimited JSON-RPC 2.0 on stdio,
+  exposing `search` / `read` / `status`. Hand-rolled on the standard library to
+  keep the zero-dependency promise; interoperability is asserted against the
+  official Python SDK in the test-suite rather than assumed. Tool schemas
+  measure ~1543 characters (~385 tokens) resident, with a test guarding that
+  budget.
+- **Use-case layer** (`dsh_kb.service`) shared by the CLI and the MCP server, so
+  `--json` output and tool results cannot drift apart.
+- **86→122 tests**: unit, end-to-end over a fixture bundle, transport tests with
+  a stub `smbclient`, CLI smoke tests, MCP protocol/process tests, and an
+  SDK interop test; no network needed.
+
+### Fixed
+
+- **`--home` did not relocate `config.json`.** The file was loaded from the
+  environment-derived home *before* overrides were applied, so
+  `dsh-kb --home X` silently ran on the built-in defaults — even though the
+  CLI's own help calls `--home` the "state directory (mirror, index, manifest,
+  logs, config)". Measured on a real deployment: three `never` path exclusions
+  and every zone's `inject` flag were ignored, and the exclusions are a privacy
+  guard. `home` is now resolved before the file is read; covered by regression
+  tests that fail without the fix.
+
+- **`WebdavSource.write` did not create parent collections.** A bare `PUT` into
+  a missing collection is just `HTTP 500 errno 2 No such file or directory`, and
+  because `MKCOL` does not recurse, every level must be created in turn. Found
+  the honest way: a 217-file import into a freshly laid-out bundle failed 217
+  times. Collections already handled are remembered per instance, so a bulk
+  import does not repeat them.
+
+- **Token and resource thrift** (the base is meant to be a supplement consulted on
+  demand, not standing context): tool schemas trimmed 1543 → 1289 characters
+  (~385 → ~322 tokens), the `instructions` line rewritten from "search before
+  reading files" (which invited a lookup every turn) to an explicit on-demand
+  stance, all zones set to `inject: false`, and an empty refresh **no longer
+  rebuilds the index** — the scheduler's four daily runs and the pre-search
+  auto-refresh are now a directory walk when nothing changed.
+- **Unknown `config.json` keys are ignored and reported** instead of crashing the
+  CLI with a `TypeError`; `doctor` lists them as a warning. Found the honest way:
+  a stray note key took the whole command down.
+
+### Known limitations
+
+- Search is lexical only. A paraphrase with no shared wording returns nothing;
+  a semantic fallback is planned but not implemented.
+- Relaxation to a broader `OR` match is deliberately *not* applied to a single
+  latin word or identifier — `UNIQ-…` is matched exactly or not at all.
+- No write path for the model: writes go through `push` into `_incoming/` and
+  are promoted to a zone by a human or a scheduled job.
+- The WebDAV client speaks the subset of RFC 4918 this project needs
+  (`PROPFIND`, `GET`, `PUT`, `MKCOL`, `DELETE`); no locking or `COPY`/`MOVE`.
+- `source=smb` costs one process and one round trip per file; it is a fallback,
+  not a replacement for a mount.
+- The MCP server implements the three methods an agent needs; prompts,
+  resources, sampling and subscriptions are not advertised.
+
+### Added before the first public release
+
+- **`skills` subcommand and MCP tool** for a curated skill library kept in a
+  `z3-skills` asset zone.  Such a zone has to be registered in `config.json`
+  (`index: false`) *before* anything is moved into it: `index_allows()` lets
+  **unregistered top-level directories through**, so moving files alone does not
+  keep them out of the index — and 2.3k `SKILL.md` files would otherwise drown
+  knowledge-page retrieval.  Both entry points forward to the library's own
+  `bin/find.py`, keeping tokenisation and scoring in a single implementation, and
+  the library's location is resolved from configuration (`DSH_KB_SKILLS_LIB` →
+  `<source root>/z3-skills/skills-library` → `~/kb/z3-skills/skills-library`) —
+  never hardcoded.
+- **`--prune` on the scheduled refresh**: the mirror is a derived cache, so files
+  deleted upstream must not linger locally and get re-indexed.
+
+### Changed before the first public release
+
+- MCP resident cost 1289 → 1674 chars (~353 → ~450 tokens) with the fourth tool;
+  the schema budget in tests moved 1500 → 1800 and the docs' cost table follows.

dsh_kb-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for looking. This project is small on purpose, and a few of its rules are
+load-bearing — please read the short list below before sending a patch.
+
+## Running the tests
+
+No dependencies, no network, no fixtures to download:
+
+```bash
+python -m unittest discover -s tests -t . -v
+```
+
+There is nothing to install. If you find yourself needing `pip install` to run
+the suite, that is a bug worth reporting.
+
+## House rules
+
+**1. Zero runtime dependencies.** This is the headline feature, not an
+accident. A pull request that adds a runtime dependency needs a very good
+reason and a discussion first. Standard library only.
+
+**2. The tests stay offline.** Every test must pass on a machine with no
+network and no shares mounted. Transport tests use fakes and stubs (see
+`tests/test_sources.py`, which drives the SMB parser through a stub
+`smbclient`). If a feature cannot be tested offline, design it so it can.
+
+**3. The MCP server is hand-rolled.** `src/dsh_kb/mcp_server.py` speaks
+newline-delimited JSON-RPC on the standard library, and
+`tests/test_mcp.py` proves it against the *official* MCP SDK. Do not replace it
+with the SDK: dependency drift would become our users' problem.
+
+**4. Docstrings explain *why*.** The code says what it does. Comments earn their
+place by recording a reason, a constraint, or a scar. Where a bug was found the
+hard way, the comment says how — several do, and they are the most useful lines
+in the repository.
+
+**5. Privacy invariants must not regress.** These are enforced by tests:
+
+* the `z2-sensitive` zone is **never mirrored to disk**, not merely skipped at
+  query time;
+* SQLite never lives on a network share (its locking is unsound there);
+* writes by an agent are proposals into `_incoming/`, never edits to a zone;
+* the `never` list is applied at the mirror *and* the index layer.
+
+## Adding a transport
+
+Transports implement the small interface in `src/dsh_kb/sources.py`:
+
+```python
+def walk(self) -> list[Entry]: ...          # the whole tree, one call
+def read(self, rel: str) -> bytes: ...
+def write(self, rel: str, data: bytes) -> None   # optional
+def describe(self) -> dict: ...             # for `doctor` and `status`
+def ensure_available(self) -> None: ...     # raise SourceUnavailable with a sentence a human can act on
+```
+
+Two things matter more than the mechanics:
+
+* **errors must read as sentences.** `ESTALE` becomes "the share looks stale:
+  remount it". A raw traceback is a bug.
+* **writes must create their own parents.** `MKCOL`/`mkdir` do not recurse;
+  a bare `PUT` into a missing collection fails with an opaque 500.
+
+## Commits
+
+English, imperative, a short subject and a body that explains the *why*:
+
+```
+fix: create missing parent collections on WebDAV writes
+
+A bare PUT into a missing collection is HTTP 500 errno 2, and MKCOL does not
+recurse. A 217-file import failed 217 times before this existed.
+```
+
+## Reporting a problem
+
+Open an issue with the command you ran, what you expected, and what happened —
+`dsh-kb doctor` covers a lot of ground and its output is usually the fastest
+path to a diagnosis. For anything security-related, see [SECURITY.md](SECURITY.md)
+instead of opening a public issue.

dsh_kb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-kb contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dsh_kb-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# The source distribution should be enough to read the project and run its
+# suite: the docs are part of the deliverable, and the tests are deliberately
+# dependency-free so a reader can verify the claims without installing anything.
+include README.md
+include README.zh.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include LICENSE
+include examples/config.json
+include examples/demo.sh
+recursive-include docs *.md
+recursive-include tests *.py

dsh_kb-0.1.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: dsh-kb
+Version: 0.1.0
+Summary: A personal Markdown knowledge base with a local mirror and index, built to be queried cheaply by AI agents.
+Author: dsh-kb contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LUgABeEEE/dsh-kb
+Project-URL: Documentation, https://github.com/LUgABeEEE/dsh-kb#readme
+Project-URL: Source, https://github.com/LUgABeEEE/dsh-kb
+Project-URL: Issues, https://github.com/LUgABeEEE/dsh-kb/issues
+Project-URL: Changelog, https://github.com/LUgABeEEE/dsh-kb/blob/main/CHANGELOG.md
+Keywords: knowledge-base,markdown,full-text-search,sqlite-fts5,ai-agents,local-first,webdav
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dsh-kb
+
+**A personal knowledge base for AI agents: the source of truth lives on shared
+storage, each machine keeps a mirror and an index, retrieval is fast and works
+offline.**
+
+English | [中文](README.zh.md)
+
+---
+
+## Who it is for, what it costs, and how to try it
+
+**For** one person (or a small team) whose knowledge already lives in a Markdown
+folder — on a network share, a NAS, or just a directory — and whose agent keeps
+re-reading it. Not a hosted product, not a multi-tenant service, not a
+note-taking UI: one machine, one bundle, one owner.
+
+**What it costs**: Python ≥ 3.10 and **no dependencies** — no daemon, no server,
+no database service, no root. One process per command. State (mirror + index)
+lives under `~/.dsh-kb` and runs about 1.9× the size of the bundle; the index is
+local, so a share that is offline or slow costs you freshness, not availability.
+
+**Try it in two minutes** — no share and no config file needed:
+
+```bash
+git clone https://github.com/LUgABeEEE/dsh-kb && cd dsh-kb
+bash examples/demo.sh          # builds a throwaway bundle, indexes it, searches it
+```
+
+---
+
+## The problem
+
+Personal knowledge — notes, lessons learned, decisions, project records —
+usually ends up scattered across session transcripts, a memory plugin, a pile
+of Markdown reports and a network share. So every agent session does the same
+thing: it **re-reads several sources**, **stuffs raw text into the context
+window** (one measured deployment re-sent ~230 000 tokens of context per
+request), and when it still cannot find the answer it says so.
+
+dsh-kb collapses that into one path:
+
+```
+one Markdown directory on shared storage     ← single source of truth
+        │  incremental pull
+        ▼
+local mirror + local FTS5 index              ← milliseconds, works offline
+        │  two narrow tools
+        ▼
+the agent asks for "path + line + 240-char snippet"
+```
+
+**The size of a result is independent of the size of the corpus** — 200 pages or
+10 000 pages, a search returns roughly 2.4 KB. That property is the whole point:
+growing the knowledge base does not make each lookup more expensive.
+
+---
+
+## Core ideas
+
+| # | Idea | Why |
+|---|---|---|
+| 1 | **One source of truth, a derived mirror** | The mirror is never an authority, so **merge conflicts cannot happen**; refreshing is a pure function of `(remote listing, manifest)` — interruptible and cheap to run often |
+| 2 | **The index is local and never on the share** | SQLite's locking is not reliable on network filesystems; the index is a disposable derivative that can always be rebuilt |
+| 3 | **Privacy zones compiled into code** | A sensitive zone is **not even copied to disk**, is not indexed, and is not returned by a default query — three layers, no conventions required |
+| 4 | **Proposal-based writes** | An agent only writes to `_incoming/`; promotion is done by a human or a scheduled job — this prevents "a dozen contradictory near-duplicates about one topic" |
+| 5 | **Precision first, recall second** | A query starts as a strict `AND`; only when that is empty does it relax to `OR`, and then **generic terms are dropped first** — otherwise a single shared word such as `UNIQ` drags in unrelated documents |
+
+Rationale and measurements: [docs/design.md](docs/design.md).
+
+---
+
+## Install
+
+Standard library only, no third-party dependencies (Python ≥ 3.10):
+
+```bash
+pip install -e .          # or simply PYTHONPATH=src python3 -m dsh_kb
+dsh-kb --version
+```
+
+---
+
+## Quick start
+
+### 1. Create a bundle (a directory on shared storage)
+
+```
+<share>/kb/
+  index.md                 # optional: progressive-disclosure front door
+  log.md                   # optional: change log
+  z0-public/               # public zone
+  z1-restricted/           # restricted zone
+  z2-sensitive/            # sensitive zone (not mirrored, not indexed)
+  _incoming/               # proposals (the only place an agent writes)
+  _meta/                   # conventions, registry, receipts
+```
+
+### 2. Configure
+
+Configuration lives in `~/.dsh-kb/config.json` — deliberately **outside any
+checkout**, so a public clone never carries your paths or private data:
+
+```json
+{
+  "source": "auto",
+  "mount": "/mnt/nas/kb",
+  "local_root": "/srv/kb-share",
+  "webdav_root": "https://nas.example.com:5000/webdav/kb",
+  "stale_minutes": 15
+}
+```
+
+`source=auto` picks the first usable option in the order **mount → local
+directory → Samba (smbclient) → WebDAV**. Walking a local filesystem tree takes
+milliseconds; WebDAV costs one PROPFIND per directory (~55 ms on a consumer
+NAS), so prefer a mount when you have one. Paths may be written POSIX-style, as
+a Windows drive, or as a UNC path (`Z:\kb`, `\\nas\share\kb`, `/mnt/nas/kb`) —
+all are normalised.
+
+> **Samba/CIFS mounts need extra care** (we hit all of these in production): a
+> mount can be `rw` and still read-only for the account; a dropped session makes
+> the whole tree raise `ESTALE`; and timestamps have **one-second** granularity.
+> All three are handled explicitly — see
+> [docs/deployment.md](docs/deployment.md#samba--cifs-mounts-linux-and-windows).
+
+### 3. Pull, index, search
+
+```bash
+dsh-kb doctor                       # check source reachability and mirror hygiene
+dsh-kb refresh                      # sync + index — what a scheduler should call
+dsh-kb search "mount stale" -n 5
+dsh-kb search "UNIQ-000123" --json  # machine-readable
+dsh-kb read z0-public/mount.md --start 1 --lines 40
+dsh-kb push                         # upload local _incoming/ proposals
+```
+
+**Only `sync`, `push` and `doctor` write to the share** (and `doctor` writes just
+two probe files — see the CLI table). `diff` also *reads* the source listing (to
+report what changed remotely), but it never writes to the share, the mirror or
+the index — it is safe to call from a timer. The share can be offline, a
+certificate can expire, a laptop can be away — search still works. This is a
+hard requirement: otherwise "offline capable" is a lie.
+
+---
+
+## Privacy model
+
+| Zone | Mirrored locally | Indexed | Returned by default |
+|---|---|---|---|
+| `z0-public` | ✅ | ✅ | ✅ |
+| `z1-restricted` | ✅ | ✅ | ✅ (`inject: false`, for injectors to respect) |
+| `z2-sensitive` | ❌ **never copied** | ❌ | ❌ (requires explicit `--zone z2`) |
+| `z3-skills` | ✅ | ❌ **never indexed** (once registered) | ❌ (own entry point: `dsh-kb skills`; 2.3k `SKILL.md` would drown retrieval) |
+| `_meta/`, `_incoming/` | ✅ | ✅ | ✅ (layout, not private content) |
+| paths matching `never` | ❌ | ❌ | ❌ |
+
+`never` defaults to `credentials`, `.credentials`, `secrets`, `id_rsa`, `密钥`
+("keys"), `密钥库` and is extendable. All three enforcement points are covered
+by tests.
+
+> **`z3-skills` is not built in.** Register it in `config.json` with
+> `"index": false` *before* moving files into it — an unregistered top-level
+> directory is mirrored **and** indexed. See
+> [`examples/config.json`](examples/config.json).
+
+---
+
+## CLI
+
+| Command | Writes? | Purpose |
+|---|---|---|
+| `status` | — | configuration, source, mirror and index state, freshness |
+| `doctor` | ✔ probes | per-check diagnostics, including "does the mirror contain anything it should not" (writes two probe files, see below) |
+| `diff [--incoming-days DAYS] [--json]` | — (reads the source) | read-only health report: remote changes, local mirror gaps, index drift, backlog, conflicts, escapes |
+| `rag-check [--prune] [--force]` | only with `--prune` | vector store ↔ index consistency, page **and chunk** level; report-only (dry-run) by default |
+| `sync [--prune] [--full] [--dry-run]` | ✔ | incremental pull; `--prune` is opt-in; `--full` ignores the manifest |
+| `index` | ✔ (local) | rebuild the index |
+| `refresh [--prune] [--full]` | ✔ | sync + index |
+| `search <q> [-n] [--zone] [--snippet] [--refresh] [--no-auto-refresh] [--json]` | — | ranked search |
+| `read <path> [--start] [--lines] [--json]` | — | line window |
+| `skills search\|show\|stats` | — | query the skill library in the `z3-skills` asset zone |
+| `push [files…] [--force] [--expect SHA256] [--log [N]] [--json]` | ✔ | upload proposals |
+| `mcp` | — | run the MCP server on stdio (for agent hosts) |
+
+Shared flags are accepted before or after the subcommand.
+
+**Not everything labelled "diagnostic" is read-only.** `doctor` is the one
+exception: it creates and deletes a probe file in `home`, and — when the source
+exposes it — writes and deletes a probe under `_incoming/` on the share, to
+answer "can `push` work at all?". The probes are removed again; nothing else is
+written. Don't wire `doctor` into anything that must be strictly read-only.
+
+**Exit codes.** `diff` and `rag-check` share one contract: **0** clean, **10**
+something needs a human, **11** local state is unreadable / the store is broken.
+`rag-check --force` without `--prune` is a *usage* error and exits **1** — it
+would override nothing, so it refuses rather than pretending it forced
+something.
+
+### What the two reports actually compare
+
+`dsh-kb diff` compares **two pairs, in two directions**, and splits both by file
+kind (`markdown` / `other`) so image or JSON churn can't drown the `.md` diff:
+
+* *remote listing vs manifest* → `content`: what changed on the share. **Report
+  only, never an alarm** — the next `sync` converges.
+* *manifest vs local mirror* → `mirror_gaps`: what is wrong with **this
+  machine's copy**. Covers every file, not just Markdown. A local file that the
+  snapshot recorded and the disk lost is `mirror-gap` (exit 10) — it used to be
+  invisible, because remote and manifest were both unchanged while `sync` would
+  re-fetch it. Extra local files are counted but not alarmed: `sync --prune`
+  cannot delete them, so a human has to decide.
+
+`dsh-kb rag-check` compares the vector store against the index at **page**
+(`path`) and **chunk** (`path` + `startline`) granularity. The chunk view is
+what catches "one page, five chunks, only two embedded" — page-level counters
+stay at 0 for that shape. On an older store whose tables have no `startline`
+column the comparison degrades to page-level and says so in `note`.
+
+---
+
+## Configuration reference
+
+| Key | Env | Default | Meaning |
+|---|---|---|---|
+| `source` | `DSH_KB_SOURCE` | `auto` | `auto` / `local` / `mount` / `smb` / `webdav` |
+| `mount` | `DSH_KB_MOUNT` | — | mount point (Samba/CIFS, NFS, or a plain directory) |
+| `local_root` | `DSH_KB_LOCAL_ROOT` | — | plain directory |
+| `smb_share` | `DSH_KB_SMB_SHARE` | — | unmounted Samba share, e.g. `//host/share` (needs `smbclient`) |
+| `webdav_root` | `DSH_KB_WEBDAV_ROOT` | — | WebDAV collection URL |
+| `stale_minutes` | `DSH_KB_STALE_MINUTES` | `15` | auto-refresh threshold |
+| `mtime_tolerance` | `DSH_KB_MTIME_TOLERANCE` | `1.0` | mtime delta still counted as "unchanged" |
+| `snippet_chars` | `DSH_KB_SNIPPET_CHARS` | `240` | snippet width |
+| `default_limit` | `DSH_KB_DEFAULT_LIMIT` | `8` | hits per query |
+| `zones` / `never` | — | see above | policy |
+
+WebDAV secrets are read **only** from the environment or a credentials file,
+never from `config.json`:
+
+```bash
+export DSH_KB_WEBDAV_USER=me
+export DSH_KB_WEBDAV_PASSWORD=...            # or DSH_KB_WEBDAV_CREDENTIALS=<key=value file>
+export DSH_KB_WEBDAV_CERT=... DSH_KB_WEBDAV_KEY=... DSH_KB_WEBDAV_CA=...   # mutual TLS
+export DSH_KB_WEBDAV_CONNECT=192.0.2.10      # connect to an IP, verify TLS against the CN
+```
+
+---
+
+## Search behaviour
+
+- **CJK**: indexing keeps the original text *and* appends adjacent character
+  bigrams, so `挂载` matches `重新挂载` (a 2-character query, which a plain
+  `unicode61` tokenizer cannot do).
+- **Latin and identifiers**: the original text is indexed verbatim, so
+  `z2-sensitive`, `page-000123.md` and `fts5` all match.
+- **Two passes**: strict `AND` first, then a relaxed `OR` restricted to
+  *selective* tokens. Results carry `relaxed: true` and `dropped: [...]` so the
+  caller knows precision was traded for recall.
+- **Snippet location** prefers the whole query as a literal, then word-boundary
+  token hits — so searching `mount -a` reports that line, not the line holding
+  `/proc/mounts`.
+
+---
+
+## Measured performance
+
+Single Linux host, bundled SQLite with FTS5, synthetic corpus (~3.4 KB per page,
+mixed Chinese and English):
+
+| Pages | Corpus | Index build | Index size | Blow-up | Engine (worst case) | Exact identifier | CLI end-to-end |
+|---|---|---|---|---|---|---|---|
+| 1 000 | 3.3 MB | 0.38 s | 7.7 MB | 2.3× | — | — | 46 ms |
+| 5 000 | 16.7 MB | 1.6 s | 33.1 MB | 2.0× | — | — | 59 ms |
+| 10 000 | 33.4 MB | 3.2 s | 62.2 MB | **1.9×** | 29.6 ms | **0.2 ms** | **72 ms** |
+
+- End-to-end includes ~30 ms of Python interpreter start-up.
+- The spread is large: an exact identifier takes 0.2 ms, a generic keyword that
+  matches nearly everything takes 29.6 ms.
+- A search returns about **2.4 KB**, independent of corpus size.
+
+The index stays near 1.9× because the FTS5 table stores **no content**
+(`content=''`) and the text lives once in a separate `meta` table, joined back
+by rowid. Inlining the text into FTS5 measured **8.1×**.
+
+---
+
+## Agent integration
+
+**Positioning: a supplement, not standing context.** Nothing is auto-injected and nothing is searched per turn — it is consulted once, when past decisions, environment facts or history are actually needed.
+
+Two shapes, one implementation (`dsh_kb.service`), so their output cannot drift:
+
+| Shape | When | Cost |
+|---|---|---|
+| **CLI + `--json`** | any agent that can run a command | one subprocess and one tool round-trip (~30 ms) |
+| **MCP server (stdio)** | the host speaks MCP (recommended) | **~420 tokens** standing (1559-char `tools/list` + 125-char instructions, measured), one less layer per call |
+
+```bash
+dsh-kb mcp            # JSON-RPC on stdin/stdout, exposing search / read / status / skills
+```
+
+Wiring it into DSH is one `insert` (other hosts:
+[docs/agent-integration.md](docs/agent-integration.md)):
+
+```yaml
+- id: mcp-kb
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: kb
+    transport: stdio
+    command: python3
+    args: [-m, dsh_kb, mcp, --home, /srv/dsh-kb, --source, auto, --mount, /mnt/nas/kb]
+    env: { PYTHONPATH: /opt/dsh-kb/src }
+```
+
+> **Why the configuration goes in `args`, not `env`**: some hosts scrub the
+> environment of the MCP child process (credential-shaped names, stale
+> prefixes). Command-line arguments are never scrubbed. Measured: with every
+> `DSH_KB_*` variable removed and only `args` set, it still works against a real
+> share.
+
+Design choices — no `mode`/`rerank` knobs, no write tools, failures returned as
+tool results — are in [docs/design.md](docs/design.md#agent-integration).
+
+---
+
+## Status
+
+Alpha (0.1.0) with 308 tests (unit, end-to-end, transport, CLI smoke and MCP — all offline):
+
+```bash
+python3 -m unittest discover -s tests -t . -v
+```
+
+With the official MCP SDK installed, one extra **interop test** runs (a real
+client against this hand-rolled server); otherwise it skips.
+
+## Roadmap
+
+- [x] MCP server (`mcp__kb__search` / `read` / `status` / `skills`)
+- [ ] Semantic fallback, used only when keyword search returns nothing (**no vector service**)
+- [ ] Scheduled refresh (systemd timer / cron examples)
+- [ ] Chinese embedding evaluation to pick a default model
+- [ ] Optional read-only HTTP viewer
+
+## License
+
+MIT — see [LICENSE](LICENSE).