know.

CookbookBooks and writingNo. 1

A technical bookchapters, code notes and a glossary that stay in step with the software

Recipe No. 1Books and writing

For
A developer writing a book about a web framework for a technical publisher
You bring
A signed proposal with its table of contents, a git repository holding the manuscript and the sample app, and the framework’s documentation and changelog
You get
A research library beside the manuscript: a document per chapter, a finding for every concept, scope decision and open question, a glossary that builds itself, and a preview for technical reviewers
Time
An evening to set up, fifteen minutes after each writing session, and an hour each time the framework ships a minor release
Works in
know.sh on the web · your AI assistant, through MCP · a coding assistant with the plugin
Keep it
Private while you work; share one document by a read-only link when it is ready.

A framework moves faster than a book. You write chapter 7 against version 4.2, and by the time the reviewers see it 4.3 has renamed an option your example depends on. The manuscript and the sample app live in git, where you can diff them. The research that says why the chapter reads as it does lives in browser tabs, issue threads and your memory.

This recipe gives that research a home, and lets an assistant do the filing. A coding assistant with the know.sh plugin, such as Claude Code, reads your proposal, your manuscript and the framework’s documentation, and builds a document per chapter with a finding per concept, each filed as Evidence with links to the official docs and changelog. You fix it up in the editor. Because the same assistant can read your sample repository and your library in one session, it can later tell you which of chapter 7’s claims still hold against the version you have installed. The index becomes the first draft of the glossary.

The manuscript stays in AsciiDoc or Markdown in git, and your publisher’s toolchain builds the book. know.sh never sees the build, and the assistant never writes the prose.

What you will use

Shelf
One shelf for the book, say Larkspur in Practice, whose line names the framework version the book targets.
Research document
One document per chapter; the overview says what a reader can do by the end and which version the chapter was last checked against.
Finding
A finding per concept, filed as Evidence with its sources; scope choices as Decision; open items as Question.
Your AI assistant
A coding assistant with the know.sh plugin, run inside the book’s repository: it builds the chapter documents from your proposal and manuscript, then checks their claims against the installed code.
The editor
Where you correct what the assistant filed, reorder concepts, set types and Key, and add the sources it missed.
The A–Z index
The glossary: every API name (camelCase identifiers, acronyms, capitalised names) that recurs in finding titles and first lines, with the numbers of the findings that explain it.
Revisions
Shows what changed in a chapter’s notes between one release and the next, marked as yours or an assistant’s, and puts back anything a check got wrong.
Public link
A read-only preview of a draft chapter for technical reviewers, with a password and an expiry at the end of the review round.

Method

  1. 1

    Connect a coding assistant in the book’s repository

    Install the know.sh plugin once, as the terminal below shows, then start claude from the root of the repository that holds the manuscript and the sample app, and run /mcp to sign in. One session can now read your proposal, your chapters, the lockfile and the installed framework’s type definitions, and write to your library.

    That is the reason to keep the research here rather than in a notes folder: the assistant that can run your tests can also see what you promised the reader.

  2. 2

    Have it build a document per chapter

    Ask it to read proposal.md and each chapter file, then make a shelf named after the book and a document per chapter, “Chapter 7 — Data loading”, with a finding per concept the chapter teaches. Each concept is filed as Evidence: what the API does in two or three sentences, its signature in a code block, and its sources in order, documentation page first, then the changelog entry, then any design proposal. Scope choices in your proposal become Decisions; anything the docs do not settle becomes a Question.

    Tell it to title findings in the framework’s own words. The index learns from finding titles and first lines, so useLoader reaches it only if it recurs there; plain words such as caching are found with Look up (⌘K).

  3. 3

    Fix it up in the editor

    A dozen chapters come back as a hundred-odd findings in an evening. Read each chapter through and press Edit: correct what is wrong, drag concepts into teaching order, and open every source to check it says what the finding claims. A finding with no official source is a claim nobody has checked; change it to Insight until it has one.

    Mark the decisions that constrain other chapters as Key, and add a line to each concept such as “Checked against 4.2.0, 2 August.” The questions are the list you clear before a draft goes to review.

  4. 4

    Check a chapter against the code

    When a release lands, or before a chapter goes to review, ask the assistant to check it. It compares each finding with the lockfile and the example under examples/ch07, and reports each claim as holds, changed or cannot tell, with the line it checked. Have it file the report as one finding, plus a Question for anything it could not settle.

    It can fix sample code on a branch you review. The prose is yours: read the report, then edit the manuscript yourself, and update the overview with the version you checked.

  5. 5

    Treat the index as the glossary

    Open the index for the book’s shelf and read it as a reviewer would. Each API name leads to the findings that explain it, and plurals get a See. Where one finding is the definition, Highlight its first sentence; its number turns bold, so the entry points to the right page first.

    When the publisher asks for the glossary, write it from this list. It holds the API names your chapters rely on; find plain-word concepts with Look up.

  6. 6

    Send a preview to technical reviewers

    Check your contract first; some publishers restrict early previews. Ask the assistant to copy ch07-data-loading.adoc into a separate document, “Early access: Chapter 7”, converted to Markdown with a finding per section and your wording untouched. Write its overview yourself in the editor: what reviewers should look for and where to email feedback.

    Press Share, set a password and an expiry at the end of the round, and copy the link, which is shown only once. When the emails arrive, paste them to your assistant and have it file each point on the chapter’s research document as a Bug, Problem or Suggestion.

Specimen

$ claude plugin marketplace add knowsh-curtis/know-cli
$ claude plugin install know-dev@know-sh
$ claude
> /mcp
  know-dev: sign in with your know.sh account in the browser window that opens
Installing the know.sh plugin for Claude Code, then signing in with /mcp from inside the sample repository.

  1. You

    Check chapter 7 against the sample app. The findings are in “Chapter 7 — Data loading” in know.sh; the code is in examples/ch07. Report only; do not touch the manuscript.

  2. research_list_findingsRead 9 findings from Chapter 7 — Data loading

  3. Claude Code

    The lockfile has larkspur 4.3.0; the chapter says it was checked against 4.2.0. I compared each finding with node_modules/larkspur/dist/index.d.ts and the example code.

    • 1, Route loaders: holds.
    • 3, Loader caching: changed. The cache option is now revalidate; the example still passes cache and logs a deprecation warning.
    • 6, Deferred data with defer(): cannot tell. It is still exported, but marked @experimental.
    • The other six hold.
  4. finding_addAdded “Drift check against 4.3.0” to Chapter 7 — Data loading, 10
  5. finding_addAdded “Is defer() stable in 4.3?” to Chapter 7 — Data loading, 11

  6. Claude Code

    Filed. Want me to update examples/ch07/loader.ts to use revalidate on a new branch?

Claude Code reads the chapter’s findings and the installed framework in one session, and files what it found as findings, not edits.

Larkspur in PracticeNo. 14

Chapter 7Data loading

11 findings, 3,940 words, about 17 minutes, filed 2 August, revised 19 September, 4 highlights.

By the end of this chapter a reader can load data for a route, cache it sensibly and stream the slow parts. Checked against Larkspur 4.2.0 on 2 August; drift check against 4.3.0 on 19 September, see finding 10.

The sample code is examples/ch07 in the book repository; the manuscript is ch07-data-loading.adoc.

Findings

  1. 1Route loadersEvidence, keyA loader runs on the server before the route renders; its return type flows into the component’s props. Sources: docs, “Loading data”; 4.0 release notes.
  2. 2Loader errors and the error boundaryEvidenceA thrown response renders the nearest error boundary; a thrown error renders it with a 500.
  3. 3Loader cachingEvidence, 1 noteRenamed in 4.3: cache became revalidate. The example still uses the old name.
  4. 4Form actions belong in chapter 8Decision, keyReaders need loaders before mutations make sense. Chapter 7 mentions actions once, with a forward reference.
  5. 5Does streaming work on the edge adapter?QuestionThe docs say yes; issue 4127 says not with compression on. Test before the review draft.

and 6 more findings

A chapter’s research document: the version it was checked against in the overview, then concepts as Evidence, scope as a Decision and open items as Questions.

Prompts to try

  1. A coding assistant with the know.sh plugin, such as Claude Code

    Read proposal.md and chapters/ch07-data-loading.adoc. Using know.sh, create a document “Chapter 7 — Data loading” on my Larkspur in Practice shelf with one Evidence finding per concept the chapter teaches: what it does, its signature in a code block, and sources from the official Larkspur documentation and changelog only. File scope choices from the proposal as Decision findings and anything the docs do not settle as Question findings. Do not change the manuscript.

  2. A coding assistant with the know.sh plugin, such as Claude Code

    Read the findings in the know.sh document “Chapter 7 — Data loading” and the code under examples/ch07. For each finding, check its claim against the framework version in the lockfile and its installed type definitions. Report each as holds, changed or cannot tell, quoting what you checked. File the report as one Evidence finding called “Drift check” in that document, and a Question finding for each thing you could not settle. Do not edit the manuscript.

  3. Your assistant, connected to know.sh (Claude, ChatGPT or a local model)

    Using know.sh, search the web for what changed between Larkspur 4.2 and 4.3 that affects route loaders, caching, streaming and form actions. Use only the official release notes, documentation and design proposals, and file what you find as a new document “Larkspur 4.3 changes” on my Larkspur in Practice shelf, one finding per change with the link to where it is announced.

  4. Your assistant, connected to know.sh (Claude, ChatGPT or a local model)

    Using know.sh, read the reviewer emails I paste below and file each point in the document “Chapter 7 — Data loading” on my Larkspur in Practice shelf: Bug for code that does not run, Problem for a passage that confused them, Suggestion for everything else. Quote the reviewer’s words, put their initials at the start of the title, and do not merge points from different reviewers.

Variations

  • Writing a second edition? Put each chapter in Focus for its week of revision, run the drift check against the new major version, and let the revisions keep the first edition’s notes.
  • Plan the production schedule as a campaign, which Claude Code can build with the plugin’s planning tools: an operation set per review round, and each chapter’s drift check blocking its review draft.
  • Not working in a repository? Any assistant connected to know.sh, Claude, ChatGPT or a local model, can file reviewer feedback and research the changelog; only the code check needs one that can read your files.
  • Writing a textbook meant to be read in the open instead? The open textbook recipe shares each chapter from the start.

Where it falls short

  • know.sh does not build or export the book. There is no PDF, EPUB, AsciiDoc or Markdown download; the manuscript and its build stay in git and your publisher’s toolchain.
  • Code blocks are highlighted while you edit, but reading mode and the public link show them as plain text, so reviewers see listings without colour.
  • Nothing runs code in know.sh. A finding marked as checked means you or your coding assistant ran it in your own repository; know.sh only stores what was found.
  • Researching changelogs on the web needs an assistant with web search; Claude and ChatGPT have it, many local set-ups do not. Connecting any assistant means signing in once, as the support page describes.

A note on previews, sources and who wrote what

Indexed under

Technical booksSample codeAPI driftGlossariesTechnical reviewEarly accessChangelogs

See also