docs(semantic-model): restructure section 8 around its argument - #439
Merged
libei merged 2 commits intoSep 16, 2026
Merged
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #433, which revised section 8's prose. This one changes its
structure and nothing else about the argument.
Replaces #436, which is the same work on a pre-rebase branch. #435 landing moved
main to
985c75band left #436 conflicting; this PR is that work rebased, plusa writing pass on top.
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.
Writing pass on the restructure
Six prose defects, in the second commit:
reads "A tool this binding" as one noun phrase.
withheldfirst appeared in a heading, 100 lines after the concept it names.The section was calling one thing by three names (
[NOT RUNNABLE], "toolsthis binding can't serve", withheld); they are bound together at first
contact now.
What a withheld tool is waiting onopened on two library field names beforethe reader has a reason to care. Those moved to
Calling it from code, whichowns the library surface.
open a connection.
Anchors, after #435
Section 7 renamed three headings. Git remapped six of the seven references
automatically during the rebase, but not the one this branch had relocated
within section 8 — git only maps a rename onto a line that stayed put, so that
site came through with a dead target and no conflict marker. Fixed explicitly:
The new target is a closer fit than the old one:
### When a rule stops the callis the subsection carrying theTransferFunds/AmountIsPositiveexpression refusal this sentence cites, and it ends on "a refusal is settled
before a session opens, so a refused action leaves no transaction behind" —
which is the claim the section 8 sentence makes.
Verification
against
origin/main: 0 lines removed, 0 added).xlinks.pyover the tree, node_modules excluded: 0 broken.bun test: 1083 pass, 0 fail.Net: 356 → 354 lines.