Conversation
Section 8 opened with a 152-line unheaded preamble -- 43% of the section -- and then five headings. The reader met `[NOT RUNNABLE]` in the listing 215 lines before learning what withholds a tool, and reference material sat in five non-adjacent places. The section was doing two jobs in one stream: making an argument (you don't write these tools) and being the reference for the derivation. Those want opposite orders. Split them into six headings, each with one job, and cut the preamble to 15 lines by naming the derivation and what it produces up front. - `The set an agent is handed` carries the command, the listing, and the gloss on `[NOT RUNNABLE]` that used to sit 138 lines later. - `Where each line comes from` carries Table 4 and, now adjacent to it, who owns each half of the instruction. - `What a withheld tool is waiting on` replaces `A tool says whether it can be called`, and the judged-guard contrast moves in beside the write-tool reason it demonstrates. - `Who owns the instruction` is folded into the provenance heading, where the table has just shown `ai_context.instructions` becoming the instruction. Corrects one claim while moving it. `kcmd agent tools` did not "read your model and nothing else": it resolves the store your profile binds, and a model whose profile binds none prints `offers no tools under this profile.` and exits non-zero. It does open no connection and run nothing, which the sentence also said and which is true. Every fenced block is carried across byte-identical.
Six defects from the manual checklist, all prose: - A garden path in subject position: "A tool this binding can't serve is..." reads "A tool this binding" as one noun phrase. Recast around the marker the reader has just seen in the listing. - "withheld" first appeared in a heading, 100 lines after the concept it names. Section 8 was calling one thing by three names ([NOT RUNNABLE], "tools this binding can't serve", withheld); bind them at first contact instead. - "What a withheld tool is waiting on" opened on two library field names before the reader has a reason to care. Those belong to "Calling it from code", which owns the library surface; the heading now opens on the answer it promises. - "derived from it" -- the nearest noun is "the change", not the model. - A third "It" in a chain whose previous link is the store, which can itself open a connection. - "offerable" where the document already says callable. No fenced block changed: 0 lines removed, 0 added.
|
#435 landing moved main to To land it, either force-push What the rebase had to resolve. Two conflicts, both in Section 7 renamed three headings. Git remapped six of the seven references automatically, but not the one this PR had relocated within section 8 — git only maps a rename onto a line that stayed put, so that site came through with a stale target and no conflict marker. Fixed explicitly: The new target is a closer fit than the old one: Verification after the rebase
Also in this push: a writing pass over the restructure (
|
1 participant
Follow-up to #433, which revised section 8's prose. This one changes its
structure and nothing else about the argument.
What was wrong
Section 8 ran 356 lines: a 152-line unheaded preamble (43% of the section)
followed by five H3s. Three consequences:
[NOT RUNNABLE]in the listing at line 1301, learned who addsit at 1412, and learned why at 1441 — a 215-line gap, for the marker
that carries the section's point about binding.
places.
Calling it from coderan 74 lines over three distinct topics.The underlying cause is that the section does two jobs in one stream: it makes
an argument (you don't write these tools; they're derived) and it is the
reference for the derivation. Those want opposite orders.
What changed
Six headings, each with one job; the preamble drops to 15 lines because the
derivation and its three products are named up front instead of 143 lines in.
## 8. Hand it to an agent+ 15-line opening### The set an agent is handed[NOT RUNNABLE]gloss in place### Where each line comes from### What a write tool and a lookup tool do### What a withheld tool is waiting on--judgecontrast beside the reason it demonstrates### Calling it from code### The commerce demo, worked through### A tool says whether it can be calledis gone; its opening paragraph movedup under the listing and the rest became
What a withheld tool is waiting on.### Who owns the instructionis folded into the provenance heading, whereTable 4 has just shown
ai_context.instructionsbecoming the instruction.Six exceeds the guide's usual five H3s per section. Five was reachable only by
merging tool provenance with tool capability, which would recreate the
74-line two-topic heading this is meant to fix.
One claim corrected
kcmd agent toolsdid not "read your model and nothing else". It resolves thestore your profile binds (
commands.ts:1352,:1379), and a model whoseprofile binds none prints
offers no tools under this profile.and exitsnon-zero (
:1387). The same sentence also said it opens no session and changesnothing, which is true —
runtime.ts:176resolves a store withoutconnecting, and the listing calls no model.
Verification
against
origin/main: 0 lines removed, 0 added).(
#8-hand-it-to-an-agentand the four inbound-linked ones) intact. Nosection-8 H3 anchor is linked from anywhere in the repo, checked with
git grep -ho 'actions\.md#[a-z0-9-]*'.npx bun test: 1083 pass, 0 fail.Net: 356 → 354 lines, 69 insertions / 71 deletions.