shelfmark CLAUDE.md

shelfmark

Product repo for shelfmark — a local, privacy-first document catalogue + MCP server. README.md is the operator-facing document; this file is for working on the code.

The bet

Every incumbent sells access to complexity. The retrieval stacks sell knobs — chunk size, overlap, embedding model, top-k, a reranker to repair what the retriever got wrong. The document-management systems sell an administration console: taxonomy editors, permission matrices, workflow builders. Desktop search sells a query syntax and calls it power. All of it hands the user machinery and lets that count as capability.

Radical simplicity on top of genuine sophistication is the harder engineering problem, and the one nobody in this category has solved.

Here that reads: corpus_stats(), then browse_folder(). Nothing to chunk, no embedding model to pick, no index server to run, no query language to learn, no tuning pass that decides whether the answers are any good. Underneath it: a walk kept incremental on (size, mtime, cloud residency), prune guards that refuse rather than guess, governance invariants re-asserted after every run, and an FTS layer that survives the hyphenated identifiers real corpora are full of. The user should never meet any of that.

A constraint on the code, not a slogan:

• The sophistication goes in the engine; the surface stays small. Five MCP tools, one config file, one command to stay current. A caller should never need to know how any of it works, or be handed a flag to compensate for something the engine could have decided.
• A new option is a failure to decide. Before adding a flag, a filter, or a config key, establish that the right answer genuinely varies by operator. If it does not, pick it and defend the choice in a comment. Corpus vocabulary varies — that is what config is for. Correct behaviour does not. --force earns its place only because the engine provably cannot tell an unreadable root from a real deletion.
• Answer the question, do not expose the machinery. browse_folder answers "what do I have here"; it does not hand back a query builder. A cut list says it was cut, an unknown filter says it is a bad filter, and corpus_stats() volunteers its own freshness — none of that is a status field left for the caller to interpret. An index answering confidently from a frozen snapshot is the failure this whole design exists to prevent.
• Simple is not thin. Dropping a feature is not simplicity if it moves the work onto the operator. Both fixes in this repo's recent history added engine complexity to remove operator burden — detecting placeholder slide titles is more code than storing whatever OOXML hands you, and explaining a refused prune is more code than exit 1. That is the trade this project accepts, every time.
• The refusals are the shape of the bet, not a backlog. "No embeddings" and "no content extraction" are decisions. Revisit them when real misses cluster into evidence — never because a competitor lists the feature. misses.py is what supplies that evidence, and the load-bearing part is the reachable/unreachable split: a raw count of misses only proves people search. Function words are stopped for the same reason — "said" can never be in a filename, so leaving it in votes for content extraction on the strength of grammar.