Introduction

gonk is one binary that holds a durable RDF store and serves a work ledger from it: items, comments, labels, links, claims, and a ranked answer to what should I do next. Around that it can serve a repository browser, explanations of what it browses from a model it mounts, a review queue that a person drains, and three doors to all of it: HTTP on loopback with a browser face, an owner-only Unix socket, and QUIC for other machines.

None of that is gonk’s own code in the sense that matters. The ledger is ikigai-ledger, the store is ikigai-store, the browser is ikigai-browse, and the doors are ikigai’s own transports. gonk is the host that composes them, which is why this book can show each one twice: as modules in a kernel you build, and as the server.

The ways to use it on its own

Each part is one way gonk is used standalone, and each builds on the one before it.

• A ledger of your own. File, comment, link, claim, close and ask next — in this page, in a kernel of your own, and against a gonk you start. Then the same ledger in a browser.
• An agent’s ledger. The ledger reached from another process over the socket, the way an agent’s tool calls reach it; and over MCP, where ikigai mcp projects the ledger’s actions as an agent’s tools, through a door that names the agent.
• The repository browser. A repository’s tree and files as resources, and an explanation of each derived once per content version, from a model gonk mounts rather than links.
• Review without a reviewer. One-off review, what a finding is, and the audit protocol that replaced per-commit review — with the measurement that retired it.
• A spec in the repository. OpenSpec keeps requirements, scenarios, changes and tasks as Markdown in an openspec/ tree. Lifted to RDF with an ikigai-markdown mapping, a change’s tasks become ledger items and next ranks them.
• Bridges. Filing roborev findings as ledger items; importing a kata ledger; checking out the repositories gonk browses and keeping them current; and all three in order on a fresh machine.
• Several machines. The three doors, the grant each runs under, and a QUIC client.
• Scripts and sentences. A query saved at a name and run by a person and a worker; a query drafted from a sentence by a machine and published by a person; and what each door may do with either.
• Several teams. Two teams’ ledgers in one gonk, an agent for each and a manager over both: one query answering each caller by its grants, a join across the teams and the code review, a report one team publishes that the other cannot run, what a signed-out caller and a deleted item show, and each identity’s tool list.
• Ways of working. Processes rather than features: one person and an agent on one machine; a dispatcher and remote workers; review on every commit; hub and spoke; spec first; and periodic unled audits. Each chapter answers the same questions in the same order (who holds which role, what runs where, the loop step by step, what holds it, and what it costs), and links back to the chapters that teach its machinery rather than teaching it again. The last, harness engineering, is about the controls around any of them: the rules and checks as a graph, a log of every time a check fires, and the questions that say which rules nothing checks and which checks have never fired.
• Embedding. The ledger, the store and browse in a kernel of your own, with no gonk at all.

Three kinds of example, and how each is checked

A tutorial’s examples rot silently, and the first reader to hit a stale one assumes they are the problem. So every example in this book is one of three kinds, and each kind has a check that fails when the example stops telling the truth.

The third kind is new in this repository. A transcript names the check it is under in a comment above it, and one that cannot be run (opening a browser, say) says so and why — a transcript nobody runs fails the check rather than passing it. Where an answer contains something minted at run time, an item’s id or a timestamp, the page prints … in its place, and the check reads … as “anything here”.

Which gonk

gonk is not on crates.io yet. This book pins it to one git revision, held in one place (books/gonk/gonk.rev) that the book, the transcript check and CI all read, and installs it from there:

$ cargo install --locked --git https://github.com/ikigai-rs/ikigai-gonk --rev 3edf8304a1a201f83e6bce13f60741d8764de5aa

The modules it links are published crates: ikigai-core 0.1.99, ikigai-ledger 0.11.1, ikigai-store 0.2.21, ikigai-browse 0.18.8, ikigai-script 0.3.3 and ikigai-nl 0.4.0. The book’s own crates (the ones its Rust listings and in-page cells run) take the newest releases, one step ahead of that: ikigai-core 0.1.103, ikigai-ledger 0.12.0, ikigai-store 0.2.23, ikigai-browse 0.18.9 and ikigai-script 0.3.6. So a console block is answered by gonk’s releases and a listing or a cell by the newer ones. No page prints differently because of it (the newer releases add a ledger item’s children to its JSON face, refuse a query whose GRAPH names a graph outside its set, and trace the kernel’s own operations). Only one page here meets any of those through gonk: Two teams, one gonk sends gonk a query whose GRAPH names a graph outside its set, and says what gonk’s store, one release short, answers instead. It serves scripts and drafting at urn:script:* and urn:nl:*.

What each move of these pins changed for a reader, and the pages that show it, is on the What’s new page.

Where a chapter needs a model, its kernel binds a stub at urn:llm: that answers the same thing every time: no example in this book calls a real model or the network. From Your first saved query on, a page also starts that stub as a process of its own, model-stub, for gonk to mount. It is this book’s own crate (crates/model-stub), not published anywhere, so it is installed from this repository:

$ cargo install --locked --git https://github.com/ikigai-rs/ikigai-tutorial model-stub

From Over the socket on, a page also runs ikigai, the command-line host, as the other process that reaches gonk. It IS on crates.io, so it is pinned to one exact version, in one file (books/gonk/ikigai-cli.version) that the check and CI read the same way. It is 0.1.61, the release whose transports the pinned gonk was built with, so it speaks the same wire, and its own ikigai-core (0.1.99, as gonk’s) words a refusal at a family scope the way gonk does, which Over the socket prints. (0.1.62 and 0.1.63 are newer and change no wire; the rule takes what gonk links, and the book’s crates take 0.1.63.) The QUIC keep-alive a client sends since 0.1.56 is answered by this gonk’s door, so a call that is silent for a while (a real model drafting or explaining) is not lost over quic://.

$ cargo install --locked ikigai-cli --version 0.1.61 --features quic

--features quic is for the pages where ikigai reaches gonk from “another machine” over its QUIC door, the first of them Over MCP; without it the command line refuses a quic:// address, and everything before that chapter works either way.

Each Ways of working chapter ends with the gonk starter, a template repository whose tools/new.py generates a repository set up for that process, and Harness engineering uses the harness it generates. The starter is pinned the same way, to one git revision in one file (books/gonk/starter.rev), and those pages clone it and check that revision out themselves. It needs Python 3.11 or later and nothing else:

$ git clone https://github.com/ikigai-rs/ikigai-gonk-starter
$ git -C ikigai-gonk-starter checkout c7a501a29e93b1160f67007b080df9f2dbbe48d3

How to read this book

The published copy is at https://ikigai-rs.github.io/ikigai-tutorial/gonk/, rebuilt from main on every merge, beside The ikigai Book, which teaches the kernel this one stands on. You do not need to have read it; where a chapter leans on an idea it explains, it links there.

The book changes often. What’s new lists each change, most recent first, with the pages to read for it.

# read it (mdbook serve never builds the in-page kernel, so Run is disabled there)
mdbook serve books/gonk --open

# check that it still tells the truth
./scripts/test-books.sh          # every Rust example, and the accessibility gates
./scripts/test-transcripts.sh    # every shell transcript, against the pinned gonk

⚠ Nothing in this book touches a gonk you already run. Every transcript runs a scratch gonk on port 1070 whose config and data homes are inside the page’s own directory (--config-home, --data-home), and the check refuses any command that names 1062, a real gonk’s port, before it runs (or 1060, gonk’s own until 2026-10-12).

A gonk per chapter

Each chapter that runs commands runs them in a new empty directory of its own, the way the check runs each page, and the gonk it starts keeps both its homes there. Every one of those gonks listens on port 1070, so a chapter that starts one first asks you to stop the one an earlier chapter left running (Ctrl-C in its terminal, which stops the tee beside it too), and the same for a model-stub. Stopping loses nothing: the earlier chapter’s directory keeps that gonk’s store, and the same command started there again picks it up where it was. Starting from nothing a chapter did not make itself is also what lets you open the book at any chapter.