Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 the next chapter’s runnable cells, in a kernel of your own, and against a gonk you start. Then the same ledger in a browser, a check of what it says with the RDF Toolbox, the Dashboard over several ledgers and their agents, shown in screenshots over a seeded history, and a lifecycle of your own: the states an item moves through and the moves it may make.
  • 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.
  • A project of your own. All of it over one generated project, the starter’s library-lending sample: start it against a local or remote gonk, change its spec, turn that into items, claim, work, close with evidence, run two agents side by side, ask it questions in SPARQL, publish a workflow, set up a model, and draft a query from a sentence.
  • Pages of your own. A deployment’s own pages, which gonk calls faces: a directory of static files that gonk serves read-only from its origin, under its default CSP, and that read gonk’s routes as the person viewing them. A first page of open items built from the starter’s template, then the starter’s samples: a board for an epic, a flight plan, a project view and a claims page.
  • 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.

kindlooks likechecked by
Runnable in the pagea cell with a Run buttonthe page’s own kernel (crates/gonk-book-wasm: the ledger over an in-memory store, compiled to wasm). A test runs every cell natively, in page order, and compares its output with the output the page shows
A Rust examplea rust block, or a listing included from crates/mdbook test compiles and runs every one against the crates under crates/
A shell transcripta console block of $ lines and their outputscripts/test-transcripts.sh installs gonk at the exact git revision this book pins, runs each page’s commands in a scratch home, and compares what they print with what the page says

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 e08ac9f3020bc1b8f3aa3ebaeca55ed36788cc50

The modules it links are published crates: ikigai-core 0.2.11, ikigai-ledger 0.18.1, ikigai-store 0.3.3, ikigai-browse 0.20.8, ikigai-script 0.4.0 and ikigai-nl 0.5.0. The book’s own crates (the ones its Rust listings and in-page cells run) take the same ledger and store, so a cell, a listing and a console block all answer from one ledger. Three patch releases differ, and no page shows any of them: those crates lock ikigai-core 0.2.12, ikigai-ledger 0.18.0 and ikigai-browse 0.20.6. gonk serves scripts and drafting at urn:script:* and urn:nl:*.

This gonk’s HTTP door lets a caller with no identity read the ledgers and write nothing (gonk PR 186). Every page writes as the owner over the socket, or as a client over QUIC; the two bridges that file, Filing roborev findings and Importing a kata ledger, do both since gonk PR 212, and lead with a client of their own.

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. The automated checks use stubs instead of real models; A model of your own, later in the book, marks the commands that need a real model or the network as manual. 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 A ledger of your own 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.2.3, the release whose transports the pinned gonk was built with, so the two speak the same wire. The book’s own crates take the in-page kernel’s grammar from ikigai-engine; that is a different program and no page runs it as ikigai. 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.2.3 --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 1766b42503ae54a19a3691bd1a5b6b584d86742c

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 library lists every book, with who each is for and where to start.

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.