@dzhechkov/skills-book-digitizer 0.2.19 → 0.2.20

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/.dz-manifest.json CHANGED
@@ -9,7 +9,7 @@
9
9
  },
10
10
  {
11
11
  "path": "README.md",
12
- "sha256": "bab7d18b5d705d191925e3a088a99d4164e395013da4b1e14bdf6785591edf25"
12
+ "sha256": "325bfdc08e994a188ac28a2cccdfa10abe354ac00450ebf3739f804723876d35"
13
13
  },
14
14
  {
15
15
  "path": "book-brain-register/SKILL.md",
@@ -37,11 +37,11 @@
37
37
  },
38
38
  {
39
39
  "path": "digitize-book/SKILL.md",
40
- "sha256": "0e0346c7a9ad556baca57def423fc75082abca73e211ba4c4c278f6bdd0bb5d2"
40
+ "sha256": "cfccc93e6ab3964fa5c9ed8847c853e31192f8a240e72da421be146771277f3b"
41
41
  },
42
42
  {
43
43
  "path": "package.json",
44
- "sha256": "a4378095cfcbd8ca8fbfc05d4284a69d87c77d2d48fa6a16c4bf0e9326ec9b83"
44
+ "sha256": "639f57a8fa2892f06d12c84dffb96ca595e8cdefea4236e24e14d90d8de12dbb"
45
45
  },
46
46
  {
47
47
  "path": "scripts/book-ingest.mjs",
@@ -61,5 +61,5 @@
61
61
  }
62
62
  ]
63
63
  },
64
- "signature": "vcwDorE3jB31mDIdi2kwvF9E1CXYa6S2xQsVjRmxO9hJe7ikAMkMm6MHiFOKJNzIRYHBNw4La89ukCkrREyqCg=="
64
+ "signature": "EIh202ZgR2Pm15w6Dp4Ra5HhvdbtSYlFRIIAFC4yBzcovl/PjVLgXVi+3/8B1F22yZZ8hkTEZzVue7EXK1AuBA=="
65
65
  }
package/README.md CHANGED
@@ -157,6 +157,82 @@ the pack** under the same CP5 licence decision that gates the pack itself: copyr
157
157
  sources are publishable. Your whole personal **brain is never published** — it is a local accretion you
158
158
  back up, not a distributable.
159
159
 
160
+ ### 6. Как пользоваться оцифрованной книгой (consuming a digitized book)
161
+
162
+ Digitizing is half the loop. Four ways to make the book's methodology actually shape your work,
163
+ from one-off to standing. Vocabulary, once: a **KU** (Knowledge Unit) is one page-anchored piece of
164
+ the book's know-how; a **kuId** is its stable id (e.g. `ai-apps-ch09-p238-ku05`); the **slug** is
165
+ the short name the book got at digitization (e.g. `ai-apps`); **CP6** is the pipeline's final
166
+ checkpoint, where you optionally promote a book from the project KB into the machine-wide brain.
167
+
168
+ Prerequisites for everything below: `dz` installed, the book digitized (scenario 1), and — for the
169
+ `dz brain` commands — the book promoted into the brain (CP6 approved, or a manual
170
+ `dz brain add --project <ingesting-project> --source <slug>`). `dz brain list` shows what made it in.
171
+
172
+ **M1 — one answer, grounded (chat).** Ask with «обоснуй по книге <slug>», or pull manually:
173
+
174
+ ```bash
175
+ dz brain query "evaluation metrics for language agents" --source ai-apps
176
+ dz brain expand ai-apps-ch09-p238-ku05 # one KU's full stored content
177
+ dz brain ground "how should I eval my agent?" --source ai-apps --budget 800 --text
178
+ ```
179
+
180
+ `query` returns ranked KU hits with source + page anchors; `expand` dereferences one kuId to that
181
+ KU's full stored record (name, problem, content, page anchors); `ground --budget N --text` prints a
182
+ ready-to-paste grounding block with the top KUs inlined within ~N tokens (per `dz brain --help`).
183
+ Where the kuId comes from: the plain `query` output prints citations *without* ids — take it from
184
+ `dz brain query … --json` (`hits[].kuId`) or from the `ground --text` block, where every `[Kn]`
185
+ line carries its kuId as the first field.
186
+
187
+ **M2 — one pipeline run.** Put the obligation in the run's task description itself, e.g.:
188
+
189
+ > Дизайн обязан свериться с ai-apps через `dz brain query`; ключевые решения цитируют kuId;
190
+ > расхождение с книгой допустимо только с названной причиной.
191
+
192
+ No setup; the obligation travels inside the brief, so it works in any pipeline whose agent reads
193
+ the brief and can run shell commands — and it holds for that run only.
194
+
195
+ **M3 — whole project, while the hook stays installed.** Wire the opt-in grounding hook once
196
+ (Claude Code projects — the hook lands in that project's `.claude/settings.json`):
197
+
198
+ ```bash
199
+ dz brain init --project <dir> --k 5
200
+ ```
201
+
202
+ Prompts with enough lexical overlap with the brain then get top-K KUs (with citations) injected
203
+ mechanically before the agent answers — scenario 4 above is this same hook, including its honesty
204
+ boundary (the hook forces the context, not the completion). Off by default. To disarm: remove the
205
+ `hooks.UserPromptSubmit` entry whose command contains `brain ground` from that project's
206
+ `.claude/settings.json`.
207
+
208
+ **M4 — one pipeline, standing.** Add a stage-gate line to the rules/instructions file that
209
+ pipeline actually loads — for Claude Code e.g. `.claude/rules/<pipeline>.md`; other harnesses have
210
+ their own equivalent (`AGENTS.md`, a system-prompt file): "the design stage passes only if it cites
211
+ `dz brain query` results (kuIds) or names the reason it diverges." No hook install; scoped to one
212
+ workflow, persisted in that pipeline's rules file.
213
+
214
+ **The two-store trap (will cost you a 0-hit session).** There are TWO stores:
215
+ `dz brain query|ground|expand` read the **machine-wide brain** (`~/.dz/brain` — only what was
216
+ promoted at CP6 / `dz brain add`), while
217
+
218
+ ```bash
219
+ dz recall --books --book <slug> "<question>"
220
+ ```
221
+
222
+ reads the **project-local** book KB (`.dz/memory/books.sqlite` — only books digitized in THIS
223
+ project). Querying the wrong store answers `0 KU hit(s)` and exits 0 — no error names the mistake.
224
+ Rule of thumb: cross-project answers → `brain`; inside the ingesting project → `recall --books`.
225
+ In doubt, `dz brain list` names what the brain actually holds.
226
+
227
+ **Worked example.** You digitized "AI Apps" as slug `ai-apps` and want a feature pipeline to design
228
+ evals by the book: (1) `dz brain list` — confirm `ai-apps` is there (if not, promote as above);
229
+ (2) start the pipeline the way you normally do — the launch syntax is your pipeline's own — with
230
+ the M2 obligation line pasted into its task description; (3) the design stage runs
231
+ `dz brain query "evaluation metrics for language agents" --source ai-apps`, cites e.g.
232
+ `[ai-apps гл.9 с.239]` (semantic-similarity metrics over exact match), and expands
233
+ `ai-apps-ch09-p238-ku05` for the full text; (4) if this becomes routine, promote M2 → M4 (a rules
234
+ line) or M3 (the hook).
235
+
160
236
  ## Design guarantees — structural vs. protocol (stated honestly)
161
237
 
162
238
  Two kinds of guarantee, and the difference matters:
@@ -100,6 +100,29 @@ cross-project brain is an IP decision, exactly like CP5, so `--trusted` never gr
100
100
  | Mirror chapters 1:1 as skills | breaks triggering + context | skills = decision moments (CP3) |
101
101
  | Publish the generated pack by default | it's book-derived; distribution is the owner's | `private` default + CP5 |
102
102
 
103
+ ## After digitization: consumption modes
104
+
105
+ Four ways the digitized book gets USED — name them in the final hand-over, and print the ready M1
106
+ query for the new slug (`dz brain query "<a KU name>" --source <slug>`):
107
+
108
+ - **M1 chat, one answer:** `dz brain query "<q>" --source <slug>` → `dz brain expand <kuId>`
109
+ (the kuId comes from `query --json` `hits[].kuId` or the `ground --text` block — the plain query
110
+ output prints citations without ids); or `dz brain ground "<prompt>" --source <slug> --budget <N>
111
+ --text` for a paste-ready grounding block.
112
+ - **M2 one pipeline run:** an obligation line in the run's own task description («дизайн обязан
113
+ свериться с <slug> через `dz brain query`, цитаты с kuId, расхождение — только с названной причиной»).
114
+ - **M3 project-wide, while the hook stays installed:** `dz brain init --project <dir> --k <N>`
115
+ (Claude Code — writes `.claude/settings.json`); disarm = remove the `UserPromptSubmit` entry whose
116
+ command contains `brain ground` from that file.
117
+ - **M4 one pipeline, standing:** the same obligation as a stage-gate line in the rules/instructions
118
+ file that pipeline actually loads (Claude Code: `.claude/rules/<pipeline>.md`).
119
+ - **Two stores — never confuse:** `dz brain query|ground|expand` read the machine-wide brain
120
+ (`~/.dz/brain`, CP6/`dz brain add` promotions only); `dz recall --books --book <slug> "<q>"` reads
121
+ THIS project's `.dz/memory/books.sqlite`. The wrong store answers `0 KU hit(s)` with exit 0 — no
122
+ error names the mistake.
123
+
124
+ Full user-facing walkthrough: the pack README, «Как пользоваться оцифрованной книгой».
125
+
103
126
  ## Self-check
104
127
 
105
128
  - [ ] Resumed from the manifest (no completed phase re-run)?
@@ -107,7 +130,7 @@ cross-project brain is an IP decision, exactly like CP5, so `--trusted` never gr
107
130
  - [ ] CP6 honored — brain promotion was an explicit opt-in (default project-local; never auto-approved, even under `--trusted`)?
108
131
  - [ ] Only verified KUs fed distill; every skill claim traces to a KU?
109
132
  - [ ] Pack is `private` unless a CP5 decision says otherwise; brain kept private (never distributed)?
110
- - [ ] User got: install command + how the new skills trigger?
133
+ - [ ] User got: install command + how the new skills trigger + the consumption modes (M1 query printed for the new slug)?
111
134
 
112
135
  ## Examples
113
136
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dzhechkov/skills-book-digitizer",
3
- "version": "0.2.19",
3
+ "version": "0.2.20",
4
4
  "description": "Canonical book-digitizer skill pack — 8 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, book-brain-register (terminal promote-to-brain, CP6), source-brain-ingest (repo/dir sibling).",
5
5
  "license": "MIT",
6
6
  "author": "dzhechko",
package/sbom.json CHANGED
@@ -25,7 +25,7 @@
25
25
  "hashes": [
26
26
  {
27
27
  "alg": "SHA-256",
28
- "content": "bab7d18b5d705d191925e3a088a99d4164e395013da4b1e14bdf6785591edf25"
28
+ "content": "325bfdc08e994a188ac28a2cccdfa10abe354ac00450ebf3739f804723876d35"
29
29
  }
30
30
  ]
31
31
  },
@@ -95,7 +95,7 @@
95
95
  "hashes": [
96
96
  {
97
97
  "alg": "SHA-256",
98
- "content": "0e0346c7a9ad556baca57def423fc75082abca73e211ba4c4c278f6bdd0bb5d2"
98
+ "content": "cfccc93e6ab3964fa5c9ed8847c853e31192f8a240e72da421be146771277f3b"
99
99
  }
100
100
  ]
101
101
  },
@@ -109,7 +109,7 @@
109
109
  },
110
110
  {
111
111
  "name": "dz:canonical-json-sha256-v2",
112
- "value": "a4378095cfcbd8ca8fbfc05d4284a69d87c77d2d48fa6a16c4bf0e9326ec9b83"
112
+ "value": "639f57a8fa2892f06d12c84dffb96ca595e8cdefea4236e24e14d90d8de12dbb"
113
113
  }
114
114
  ]
115
115
  },