@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 +4 -4
- package/README.md +76 -0
- package/digitize-book/SKILL.md +24 -1
- package/package.json +1 -1
- package/sbom.json +3 -3
package/.dz-manifest.json
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
},
|
|
10
10
|
{
|
|
11
11
|
"path": "README.md",
|
|
12
|
-
"sha256": "
|
|
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": "
|
|
40
|
+
"sha256": "cfccc93e6ab3964fa5c9ed8847c853e31192f8a240e72da421be146771277f3b"
|
|
41
41
|
},
|
|
42
42
|
{
|
|
43
43
|
"path": "package.json",
|
|
44
|
-
"sha256": "
|
|
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": "
|
|
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:
|
package/digitize-book/SKILL.md
CHANGED
|
@@ -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.
|
|
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": "
|
|
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": "
|
|
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": "
|
|
112
|
+
"value": "639f57a8fa2892f06d12c84dffb96ca595e8cdefea4236e24e14d90d8de12dbb"
|
|
113
113
|
}
|
|
114
114
|
]
|
|
115
115
|
},
|