architecture.md

# Architecture decisions

The existing workspace contains portable books-pipeline exports and no prior Book Agent or Git repository. Book Agent is implemented as a cohesive sibling subproject; existing exports, production workers and archive bytes remain untouched.

1. Input v3 packages and their SQLite vectors are read-only. No chunks prerequisite, document embedding or Book Skill distillation is exposed.
2. Known schema adapters parse real metadata; unsupported schemas yield precise diagnostics. Corpus identity binds original/fulltext/database hashes rather than title/path.
3. A single BookAgent Core backs CLI and official-SDK stdio MCP. MCP contains transport/typed tool declarations, no parallel data layer. Eight bounded read/retrieval tools plus book list/status.
4. SQLite-native evidence + runtime-only lexical sidecar, multilingual substring/ngram matching and rank fusion. Natural semantic queries require inherited compatible query runtime; absent/incompatible/unauthorized dependencies cause explicit lexical_fallback or strict errors. Provided vectors reuse document vectors without model calls, with provenance limits.
5. Rerank is the only user-facing model choice: none (default), SiliconFlow, local existing CrossEncoder, custom constrained protocol. Remote query sends questions; remote rerank sends questions/candidate passages, only to explicitly approved endpoints. No remote service is enabled by importing a manifest.
6. Source maps prefer existing valid locators/Markdown offsets; PDF file-page numbers differ from printed labels, EPUB uses spine/href/anchor. Images are returned via MCP image content and runtime caches; this proves image delivery, not model interpretation.
7. Runtime registration/config/cache/sidecar/deployment use atomic updates and perbook/registry OS locks outside corpus. Changes invalidate metadata/query/locator caches. Host installations plan, back up, merge only owned entries, refuse conflicts, and uninstall only hash-matching owned outputs.
8. Windows x64 onedir is built and tested here. Linux/macOS get the same source and CI/build definitions, with no claim of executed native builds. Synthetic fixtures/evals are distributable; real copyrighted sample stays in ignored .work and never enters wheels/releases.
9. Generic releases have no personal user path, registry or credential binding. Receiving machines register identical book content at their own paths and regenerate Host argv/config. Vector queries are optional `none` (default), `offline` or `online`; default lexical retrieval and original-source access require no SiliconFlow key. Compatible original local query files are optional operational dependencies delivered/verified separately; dense retrieval never silently changes the index model. See [portability](portability.md).

## Runtime boundary

Deployment artifacts are generated in the book runtime directory. Installing into a real host requires the explicitly scoped install-host command; isolated tests never mutate user host settings. Query/visual/host capability states remain independent. stdout is JSON or MCP only; diagnostics go stderr and never include credentials.