@dzhechkov/skills-book-digitizer 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -33,6 +33,83 @@ dz init --target claude-code --select digitize-book
33
33
  Prerequisites: `poppler-utils` (ingest) and, for the KB, `dz setup --memory agentdb`
34
34
  (installs `agentdb` + `better-sqlite3`).
35
35
 
36
+ ## Usage scenarios
37
+
38
+ The digitizer produces three durable artifacts from one book: (1) an installable **skill pack**, (2) a
39
+ per-project **two-store KB** (`book-kb-index` → `.dz/memory/books.sqlite` lexical + shared agentdb
40
+ vector), and (3) a promote path into a durable cross-project **Knowledge Brain** (`~/.dz/brain/`).
41
+ Full design + the RU version: [ADR-001 Knowledge Brain](https://github.com/djd1m/dz-harness-hub/blob/main/features/book-brain/ADR-001-knowledge-brain.md).
42
+
43
+ ### 1. Digitize a book → skills + KB
44
+
45
+ The core pipeline. Install the orchestrator, then hand it a PDF; it runs `book-ingest → extract →
46
+ distill → assemble → book-kb-index` through 5 human checkpoints.
47
+
48
+ ```bash
49
+ dz init --target claude-code --select digitize-book
50
+ # then, in your agent: «оцифруй вот эту книгу — хочу, чтобы агент проектировал по её методикам»
51
+ ```
52
+
53
+ Output: a `skills-book-<slug>` pack (decision-moment skills) **and** the two-store KB behind it. Live
54
+ run: DDIA → «Высоконагруженные приложения» digitized to **116 Knowledge Units**.
55
+
56
+ ### 2. Query one book's knowledge
57
+
58
+ Lexical (FTS5) recall over a single digitized book's KB, in the project that ingested it. `--book`
59
+ narrows the search to one book slug:
60
+
61
+ ```bash
62
+ dz recall --books --book <slug> "replication topology"
63
+ ```
64
+
65
+ Pull-based: you ask, you get KU hits back with source + page anchors. No hook, no injection.
66
+
67
+ ### 3. Build a cross-project brain from N books
68
+
69
+ Promote each project's digitized-book KUs into **one shared brain** (`~/.dz/brain/` — lexical
70
+ `books.sqlite` + vector `agentdb.db`), then query across every ingested book at once:
71
+
72
+ ```bash
73
+ dz brain add --source <slug> # promote this project's KUs into the brain (idempotent)
74
+ dz brain list # what's in the brain: slug, kind, KU count, corpus version
75
+ dz brain query "replication topology" # cross-source recall over ALL books
76
+ dz brain query "replication topology" --source <slug> # optional: narrow to one book
77
+ ```
78
+
79
+ One shared store, not per-book packages: you do **not** install anything to query the brain — it
80
+ accretes on `dz brain add`. The *right* book surfaces by **relevance** (KUs rank on one common scale,
81
+ each hit labelled with its source book + page); `--source` is a label filter, not a manual routing
82
+ pick. Cross-source is the default — multiple books scoring on a query is a feature (richer grounding),
83
+ not a bug.
84
+
85
+ ### 4. Grounded answering (the hook)
86
+
87
+ ```bash
88
+ dz brain init # opt-in: wire the grounding UserPromptSubmit hook (once)
89
+ dz brain ground "<prompt>" # what the hook runs: retrieve + emit citations (or nothing)
90
+ ```
91
+
92
+ `dz brain init` (opt-in) wires a single `UserPromptSubmit` hook that runs `dz brain ground` on each
93
+ prompt. On a *relevant* prompt (relevance-gated, so it stays quiet on unrelated turns) the hook
94
+ mechanically retrieves top-K brain KUs and injects them — with source + page citations — into that
95
+ turn's context, so the agent answers **from the book, not from training data**. Off by default; a
96
+ prompt with no lexical overlap (e.g. "what's the weather") injects nothing.
97
+
98
+ Honesty boundary: the injection is **mechanical** (the hook forces the grounding block into context and
99
+ the agent literally cannot start the turn without it); "answering from it" is **agent discipline** — the
100
+ hook can force the context but not the completion. The hook is **generic and wired once** (one hook over
101
+ the whole brain across all sources — *not* per book), and needs **no edits to `CLAUDE.md` or governance
102
+ shards** — the injection channel is the hook's stdout (`hookSpecificOutput.additionalContext`).
103
+
104
+ ### 5. Sharing a digitized book
105
+
106
+ The `skills-book-<slug>` **pack** (via GitHub / `npx`) carries the behavior — the decision-moment
107
+ skills and `references/` deep-lookup. The design (ADR §8.1, P2) also ships the book's **KB slice inside
108
+ the pack** under the same CP5 licence decision that gates the pack itself: copyrighted books stay
109
+ `private: true` (structural, mechanically enforced — no auto-publish, no preset entry), permissive
110
+ sources are publishable. Your whole personal **brain is never published** — it is a local accretion you
111
+ back up, not a distributable.
112
+
36
113
  ## Design guarantees — structural vs. protocol (stated honestly)
37
114
 
38
115
  Two kinds of guarantee, and the difference matters:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dzhechkov/skills-book-digitizer",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Canonical book-digitizer skill pack — 6 skills that turn an engineering book/textbook/monograph into an installable skill pack whose skills make AI coders work within the book's methodologies: digitize-book (orchestrator), book-ingest, book-knowledge-extract, book-skill-distill, book-pack-assemble, book-kb-index.",
5
5
  "license": "MIT",
6
6
  "author": "dzhechko",
@@ -36,4 +36,4 @@
36
36
  "directory": "packages/@dzhechkov/skills-book-digitizer"
37
37
  },
38
38
  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/skills-book-digitizer#readme"
39
- }
39
+ }
File without changes