Skip to content

docs(semantic-model): restructure section 8 around its argument - #439

Merged
libei merged 2 commits into
GoogleCloudPlatform:mainfrom
libei:section8-structure-rebased
Sep 16, 2026
Merged

libei merged 2 commits into
GoogleCloudPlatform:mainfrom
libei:section8-structure-rebased

Conversation

@libei

@libei libei commented Sep 16, 2026

Copy link
Copy Markdown
Collaborator

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 985c75b and left #436 conflicting; this PR is that work rebased, plus
a 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:

  • A reader met [NOT RUNNABLE] in the listing at line 1301, learned who adds
    it at 1412, and learned why at 1441 — a 215-line gap, for the marker
    that carries the section's point about binding.
  • Reference material was 22% of the section, spread across five non-adjacent
    places.
  • Calling it from code ran 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.

heading job
## 8. Hand it to an agent + 15-line opening the claim
### The set an agent is handed command, listing, and the [NOT RUNNABLE] gloss in place
### Where each line comes from Table 4, and who owns each half of the instruction
### What a write tool and a lookup tool do unchanged
### What a withheld tool is waiting on the reasons, with the --judge contrast beside the reason it demonstrates
### Calling it from code unchanged
### The commerce demo, worked through unchanged

### A tool says whether it can be called is gone; its opening paragraph moved
up under the listing and the rest became What a withheld tool is waiting on.
### Who owns the instruction is folded into the provenance heading, where
Table 4 has just shown ai_context.instructions becoming 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 tools did not "read your model and nothing else". It resolves the
store your profile binds (commands.ts:1352, :1379), and a model whose
profile binds none prints offers no tools under this profile. and exits
non-zero (:1387). The same sentence also said it opens no session and changes
nothing, which is true — runtime.ts:176 resolves a store without
connecting, and the listing calls no model.

Writing pass on the restructure

Six prose defects, in the second commit:

  • A garden path in subject position — "A tool this binding can't serve is…"
    reads "A tool this binding" as one noun phrase.
  • withheld first appeared in a heading, 100 lines after the concept it names.
    The section was calling one thing by three names ([NOT RUNNABLE], "tools
    this binding can't serve", withheld); they are bound together at first
    contact now.
  • What a withheld tool is waiting on opened on two library field names before
    the reader has a reason to care. Those moved to Calling it from code, which
    owns the library surface.
  • "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.

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:

#why-a-guarded-action-is-refused  ->  #when-a-rule-stops-the-call

The new target is a closer fit than the old one: ### When a rule stops the call is the subsection carrying the TransferFunds / AmountIsPositive
expression 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

  • All five fenced blocks carried across byte-identical (multiset diff
    against origin/main: 0 lines removed, 0 added).
  • Prose at 80 columns; every internal link resolves; frozen anchors intact.
  • Old anchor targets repo-wide: none. Stale link label text: none.
  • xlinks.py over the tree, node_modules excluded: 0 broken.
  • bun test: 1083 pass, 0 fail.

Net: 356 → 354 lines.

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.
@libei
libei merged commit 7a02244 into GoogleCloudPlatform:main Sep 16, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant