Skip to content

Name the library call each MCP tool wraps, and search Python's native pages by section - #334

Open
tony wants to merge 55 commits into
mainfrom
fix/next-wave-followups
Open

tony wants to merge 55 commits into
mainfrom
fix/next-wave-followups

Conversation

@tony

@tony tony commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Three follow-ups from the libtmux.org design system owner: MCP tool pages name the library call each tool wraps on ten ports, the search Section facet covers Python's Sphinx-rendered pages, and the MCP replay can close on the agent's own reply.

Summary

  • Wraps rows on ten ports (record 0053, curated data only). mcp-wraps.json seeded six Go tools. It now holds 246 entries across py, ts, go, rs, java, csharp, cxx, swift, julia and ruby. Each names the library call and cites the source line that proves it at the port's pinned revision. A tool with no traceable library call gets no entry: batch and dispatch tools, waits and searches done in server code, raw tmux commands, tools whose argument picks among several calls, and the get_*_info tools. check-mcp-wraps.mjs checks every citation and runs in test-all.
  • Section facet on Python's native pages. Sphinx-rendered pages carried only the port filter, so setting Section dropped Python's API pages. Assembly now writes the same section marker the Astro layout writes, derived from the URL path: api/, genindex/ and py-modindex/ map to reference, and quickstart/ maps to guides.
  • Tier filter for Ruby and Julia. Their servers state no toolsets, and their tool pages and indexes already hid the tier badge, filter and capability row. Tests now pin that for every tool page of both ports.
  • The replay's closing reply. gen-mcp-transcript.mjs records an example's closing reply and refuses one that quotes output the session never printed. McpReplay.astro shows it as the final turn, and falls back to today's derived turn when a recording has none. The ten stored recordings need re-recording against their live servers to carry replies.

Test plan

  • check-mcp-wraps fails on a wrong line number (fixture tests) and passes for all ten ports against the checkouts.
  • Real-Pagefind test: section=reference with port=Python returns the native API page.
  • Tests for the closing reply: a passing case, two refusals, and fixture replies on Go and Julia with a no-reply control.
  • Focused tests (296), pnpm run type-check, ruff check, ruff format --check and check-api-links on the combined branch.
  • test (test-all) on this branch.

tony added 30 commits November 18, 2026 17:14
why: Python's Sphinx pages under /py/latest/api/ reached the Pagefind
index with a `port` filter and no `section`. A reader who set the
Section facet, or chose "Python API only" (section=reference), got no
Python API pages: Pagefind drops pages that lack the filtered key.

what:
- Move the layout's section rule into `pageSection` in search-state.ts
  and use it from BaseLayout.astro, so the Astro pages emit the same
  values as before
- Add `nativeSection`: a native page's path inside the Sphinx tree maps
  `api/`, `genindex/` and `py-modindex/` to reference and `quickstart/`
  to guides; every other path takes the Astro rule (`topics/` stays
  topics, the tree root is home)
- Write the layout's `<div data-pagefind-filter="section:..." hidden>`
  element before the native article, since the article's bytes must
  stay unchanged; a second assembly pass replaces it in place
- Test the mapping, the marker on normalized pages and a second pass,
  and, through a real Pagefind index, that section=reference with
  port=Python returns the native API page and section=guides returns
  both the Astro guide and the native quickstart
…without a tier

why: The Ruby and Julia servers state no toolsets, so their pages must
show no tier badge, no Toolset or capability row, and no tier filter on
the tools index, which would otherwise list an empty control. The
rendered pages already behave this way (`tiered` is false when no tool
names a toolset), but only the first Ruby tool page was checked, the
index was checked for the filter alone, and no Julia tool page was
checked at all.

what:
- Check every Ruby and Julia tool page for the tier badge, the
  `data-tier` attribute, the capability row and the Toolset term
- Check each tools index for the filter, its radio buttons, the
  per-tier counts and any tier or tier-name text, with the card count
  matching the server's tools
- Rename the Wraps test, which no longer carries a Ruby assertion
…h MCP recording

why: A recording held the prompt, the tmux state before the first call
and each call with its result, but not the agent's closing message. The
replay derived its last turn from pane output instead, which works only
for tools whose results name a pane's output: Ruby's tmux_wait and
Julia's send_keys_and_wait results are not read, so both replays ended
on their last call with no closing turn. The recorder replays the
example's own calls and runs no live agent, so the reply is the
example's, checked against what the session printed.

what:
- Give each example a `reply`; its double-quoted text is output the
  session printed ("2 passed", "checks finished")
- Add `recordedReply`: it returns the reply once every quoted value is
  in a recorded result, and refuses a reply that quotes a value the
  recording lacks or quotes nothing
- Store the reply as `reply` in the transcript, and have `--check`
  compare it when the stored recording has one, so a recording made
  before this change is not reported stale
- Test the check with a passing and two failing replies, and against
  each of the ten stored recordings, which all print what the reply
  quotes, so recording any of them again stores the reply
why: The replay's last turn came only from the answer derived from pane
output, so a recording with a stored reply could not show it and the
Ruby and Julia replays had no closing turn. The McpReplay design reads
the closing turn from the recording.

what:
- Read `reply` from the transcript into the recording, and show it as
  the closing turn with the output it quotes in `<q>`, in the turn the
  derived answer already used, so pinning and stepping are unchanged
- Keep the derived answer for a recording that stores no reply: all ten
  stored recordings, until each is recorded again
- Test the closing turn on Go and Julia with a fixture transcript that
  carries a reply, and the two controls: Go without a reply still ends
  on the derived answer, Julia without one has no closing turn
why: A Wraps row on an MCP tool page says the tool makes a library call
and links the source line that makes it. Nothing read that line, so a
wrong or drifted line number would read as proof. The data test also
pinned every cited path to Go's flat mcp/ directory, which the other
ports' servers do not use.

what:
- Add wrapsProblems: the cited file exists at the entry's revision, the
  line is inside it and names the call as a whole word, and the call is
  a library symbol of the port's API model.
- Add check-mcp-wraps.mjs, which reads each entry from the port's
  checkout with git show and skips a port with no checkout or revision,
  and run it from test-all.sh beside the MCP source-link check.
- Add fixture tests that fail on a wrong line, a missing file, a
  non-library call and a malformed source.
- Accept any path:line source in the data test and check each entry's
  repo against the MCP snapshot.
why: A Python MCP tool page named no library call, so a reader could not
tell which libtmux method a tool runs. Each entry below names the call
and the line of libtmux-mcp that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 35 entries for libtmux-mcp at its pinned revision, each naming a
  libtmux Pane, Window, Session or Server method and the file and line
  that calls it.
- Leave 19 tools without an entry: tools that run tmux through the
  server's own subprocess helper (the buffer, channel and wait tools),
  composites with no single primary call, tools that pick between
  methods by argument, and tools that only resolve a target.
why: A TypeScript MCP tool page named no library call, so a reader could
not tell which @libtmux/libtmux method a tool runs. Each entry names the
call and the line of the server that makes it, read at the revision the
MCP snapshot documents.

what:
- Add 30 entries for @libtmux/mcp at its pinned revision, each naming a
  Server, Session, Window, Pane or Program method and the file and line
  that calls it. The list and snapshot tools cite the one shared
  Server.snapshot call.
- Leave 20 tools without an entry: tools that send raw tmux commands
  through Pane.cmd or Server.cmd, wait or search in server code, choose
  a method by scope, make several calls with no primary one, or only
  resolve a target.
why: A Julia MCP tool page named no library call, so a reader could not
tell which LibTmux function a tool runs. Each entry names the call and
the line of LibTmuxMCP that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 8 entries for LibTmuxMCP at its pinned revision, each naming a
  LibTmux function and the file and line that calls it.
- Leave 3 tools without an entry: run_operations dispatches other tools,
  and send_keys_and_wait and wait_for_text match output in server code.
why: A Java MCP tool page named no library call, so a reader could not
tell which libtmux method a tool runs. Each entry names the call and
the line of libtmux-mcp that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 25 entries for libtmux-mcp at its pinned revision, each naming a
  Server, Session, Window, Pane, Options, Hooks or Channel method and
  the file and line that calls it. The kill tools cite the branch of
  the shared kill handler that ends their object.
- Leave 20 tools without an entry: tools that read through a raw
  Pane.batch or Server.cmd argv, wait or search in server code, choose
  between methods by argument, or only resolve a target.
why: A Rust MCP tool page named no library call, so a reader could not
tell which libtmux method a tool runs. Each entry names the call and
the line of tmux-mcp that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 27 entries for tmux-mcp at its pinned revision, each naming a
  Server, Session, Window or Pane method and the file and line that
  calls it.
- Leave 18 tools without an entry: batch tools, tools that run tmux
  through Server.chain or Server.cmd, server-side waits and run
  protocols, tools that pick a method by scope or argument, and tools
  that only resolve a target.
why: Six Go tools named the library call they make; the rest of the Go
MCP tool pages named none, so a reader could not tell which libtmux-go
method a tool runs. The control for a tool with no recorded call was
list_sessions, which now has one.

what:
- Add 23 entries to the six already recorded, each naming a Server,
  Session, Window or Pane method and the file and line of the mcp
  package that calls it, at the revision the MCP snapshot documents.
  Sort the Go entries by tool name.
- Leave 16 tools without an entry: batch tools, server-side waits and
  run protocols, tools that run a raw tmux command through Server.Cmd,
  tools that pick a method by argument, and tools that only resolve a
  target.
- Point the no-Wraps-row control at call_read_tools_batch, a batch tool
  that makes no single call.
why: A Ruby MCP tool page named no library call, so a reader could not
tell which libtmux-ruby method a tool runs. The two entries name the
call and the line of libtmux-mcp that makes it, read at the revision
the MCP snapshot documents. The site looks a tool up by its wire name,
which Ruby prefixes with tmux_.

what:
- Add entries for tmux_snapshot (Async::Server#snapshot) and tmux_close
  (Entity#kill) for libtmux-mcp at its pinned revision.
- Leave 6 tools without an entry: tmux_send and tmux_create choose
  between library methods by argument, tmux_capture and tmux_run go
  through private helpers that are not public symbols, and tmux_wait
  and tmux_capabilities are server logic.
why: A C# MCP tool page named no library call, so a reader could not
tell which LibTmux method a tool runs. Each entry names the call and
the line of LibTmux.Mcp that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 28 entries for LibTmux.Mcp at its pinned revision, each naming a
  Server, Session, Window, Pane, TmuxOptions, TmuxHooks or channel
  method and the file and line that calls it.
- Leave 17 tools without an entry: batch tools, tools that run through
  LibTmux.Internal readers, runners and chains that are not public
  symbols, server-side search, tools that choose a method by argument,
  and tools that only resolve a target.
why: A C++ MCP tool page named no library call, so a reader could not
tell which libtmux method a tool runs. Each entry names the call and
the line of libtmux-mcp-server that makes it, read at the revision the
MCP snapshot documents.

what:
- Add 31 entries for libtmux-mcp-server at its pinned revision, each
  naming a Server, Session, Window or Pane method and the file and line
  that calls it.
- Leave 14 tools without an entry: batch tools, tools that run a raw
  tmux argv or chain through Server::run or Server::run_chain,
  server-side search and run protocols, tools that pick a method by
  argument, and tools that only look a target up.
why: A Swift MCP tool page named no library call, so a reader could not
tell which LibTmux method a tool runs. Each entry names the call and
the line of LibTmuxMCP that makes it, read at the revision the MCP
snapshot documents.

what:
- Add 31 entries for LibTmuxMCP at its pinned revision, each naming a
  Server method, with its argument labels as the API model spells it,
  and the file and line that calls it.
- Leave 14 tools without an entry: batch tools, tools that call
  package-level symbols the API model lacks, tools that send a raw
  command through Server.run, server-side search and run protocols,
  tools that pick a method by argument, and tools that look a target up
  or combine a lookup with a capture.
…s and the replay's closing reply

why: A reader who set the search Section facet lost Python's Sphinx-rendered
API pages, which carried only the port filter; and McpReplay had no field
for the agent's closing reply.

what:
- Python native pages get the same section marker the Astro layout writes,
  derived from the URL path at assembly
- Tests pin that Ruby and Julia tool pages and indexes hide the tier filter
- gen-mcp-transcript.mjs and McpReplay record and show a closing reply
why: MCP tool pages show the library call a tool makes only when curated
data names it (record 0053); site/src/data/mcp-wraps.json seeded six Go
tools, so every other tool showed no Wraps row.

what:
- 246 curated entries across py, ts, go, rs, java, csharp, cxx, swift,
  julia and ruby, each citing the source line that proves the call at
  the port's pinned revision; tools without a traceable library call get
  none
- scripts/check-mcp-wraps.mjs checks every citation and runs in test-all

# Conflicts:
#	site/test/mcp-tool-browser.test.ts
why: The "For programs" curl command on /en/prompts/ was a hand-built pre
at `font-mono text-xs`, so it computed 12px at a 16px line height. Record
0032 of the design system sets every code block at 13px and a 1.7 line
height; the shared Expressive Code frame already carries that size.

what:
- Render the command with `<Code lang="console" frame="none">` so it takes
  the frame's size, shell prompt and Copy button.
- Add a code-size test that fails on a hand-sized pre on that page.
why: Record 0062 of the design system sets labels in sentence case, as
"API reference" already is. The .NET installer's "Script & Interactive"
and "File-Based Apps" tabs were the two title-cased labels left; the
other tabs are proper names (.NET CLI, PMC, CPM, Paket CLI, Cake).

what:
- Rename the tabs to "Script & interactive" and "File-based apps" in
  ports.ts, and the note that points readers at the first one.
- Update the NuGet recipe test that pins the label order.
why: Record 0027 of the design system says a frame shows every line unless
its author sets a cap and nothing caps by default. The site capped any
complete program of 40 lines or more at 24 lines on its own: 4 of 1,401
frames carried that cap, chosen by a line count rather than by a reader's
need. The long programs the design review flagged carried no cap at all.

what:
- Remove the 40-line default (`LONG_PROGRAM_LINES`, `PROGRAM_CAP_LINES`);
  `requestedCap` now returns the author's `height` only. `height="full"`
  and the rule that an excerpt never caps stay.
- Set `height="24"` on the programs of the Rust MCP inspect-sessions page
  (194 lines), the Rust control-mode guide (138) and the Go MCP run-command
  page (145). They are complete programs, not output; each page's output
  frames are one to three lines.
- Keep the 24-line cap, now set by the author, on the two Go examples the
  default used to cap (98 and 80 lines). The other frames it capped (41, 46
  and 66 lines) now show whole.
- Update the code-frame tests: an uncapped frame renders every line, an
  author cap applies to a program, output and plain frames, and the named
  pages carry their cap. Update the example-build-up note.
why: Record 0026 of the design system says a language without a package
for a product states that, instead of the product dropping out of the
page. On the front page a reader who chose a language such as Raku saw
Core alone with no hint that MCP and Workspace Manager exist for other
languages. The front page has no product-first picker (the language is
chosen first, in the header launcher), so the line sits with the chosen
language's solution cards. Port homes keep omitting a product the port
lacks (record 0061).

what:
- Add one line under each language's solution cards in HomeIntro naming
  the companion products it has no package for ("Raku has no MCP or
  Workspace Manager package yet."), derived from the same solutions that
  draw the cards, with no link.
- Add a front-page test that each language's line names exactly the
  products missing from its cards and that a language with all products
  has none.
…e bar

why: Records 0015 and 0047 of the design system allow a bar on the start
edge of an aside only. Two API stylesheet rules still drew one: the
contents list of an API page, glossary, MCP tool page and tmux catalog
gave its current entry a 2px link-colour border, and a tree row or member
link lit by its twin (cross-highlight) drew a 2px inset shadow.

what:
- Drop the transparent `border-left` of every contents entry and the
  `border-left-color` of the current one; the current entry keeps its link
  colour and weight 600 and takes the shared `--current-row-bg` tint.
- Drop the inset shadow of `.is-cross-lit` rows and links; their link-colour
  tint stays, which the kind-palette contrast test measures.
- Add a design-token test that finds a border or inset shadow on the start
  edge in both places, with a control that proves the pattern matches the
  old declarations.
why: In a port build the letter strip of the A-Z index linked to
/reference/symbols/<letter>/ at the site root, so every letter on a page
such as the Go index left the Go tree for the cross-port index. Each
port's index is a page of its own reference (record 0021).

what:
- Build the strip's hrefs, and the cross-port breadcrumb, from
  `referenceRoot`: the port's reference in a port build, `/reference/` at
  the root.
- Add a test that renders both builds and checks every letter link of the
  strip.
why: BaseLayout now imports `pageSection` from the search state, but the
test stubs only the helpers it listed, so the suite failed at import with
a missing export before any assertion ran.

what:
- Add `pageSection` to the helper module the layout compiles against.
why: The notice stood at one row only below 30rem. Between 30rem and
48rem its sentence wrapped to two to four rows (83px tall at 480px) before
it fit on one line at 64rem. Rendered in Chrome with the system font, the
folded form is one row of 40px at 480, 600 and 768px, the height the full
sentence has on one line at 1024px (39.6px).

what:
- Move the notice's folded form (badge, short lead, More) from the
  phone query to a `max-width: 63.999rem` query, the `bp-nav` breakpoint,
  and update the breakpoint comments.
- Rewrite the chrome-header test to read the rules from the `bp-nav` query.
why: Record 0052 sets the Japanese stack as the hashed Plex family, then
Hiragino Sans, Hiragino Kaku Gothic ProN, Yu Gothic UI, Yu Gothic, Meiryo,
Noto Sans CJK JP and Noto Sans JP, then system-ui and sans-serif. The rule
wrote `var(--font-sans)` first, and the Fonts API expands that variable to
the Plex family followed by ui-sans-serif, system-ui and sans-serif, so
those generic faces came up for kana before the named Japanese ones. CSS
cannot take the hashed family out of the variable, so the build supplies
the order.

what:
- Add `sansFallbacks(locale)`: the Japanese build lists the Japanese sans
  faces first and the generic faces after them; other locales keep their
  list. `astro.config.ts` passes it as the IBM Plex Sans fallbacks.
- Reduce the `:lang(ja)` rule to `var(--font-sans)`, which is now the
  stack in order, and update its comment.
- Rewrite the typesetting test to check the fallback order, the rule and
  that the config reads the helper.
why: The current entry of an API page's contents now carries the shared
current-row tint, so in forced-colours mode, where a tint is dropped, it
needs the system highlight like every other current row. The forced-colours
test finds each tinted current row and failed for this one.

what:
- Add the contents entry, `a[aria-current="location"]` of the page and
  glossary contents, and its descendants to the Highlight and HighlightText
  rules.
why: A frame says "Complete program" only for a whole file. The attach
guides each show one whole program (main.go, connect.py, src/main.rs and
fifteen more) and nothing quotes it, so its frame carried no role label,
while the setup files beside it (go.mod, Cargo.toml, build.gradle.kts) are
whole files that are not programs.

what:
- Add `role="program"` to the titled program fence of the generic shell
  guide and of the C#, C++, Elixir, F#, Go, Java, Julia, Kotlin, Common
  Lisp, Lua, PowerShell, Python, Rust, Ruby, Scala, Swift and TypeScript
  attach guides.
- Add a test that reads every attach guide through the fence plugin and
  requires the role on each program and on no setup file.
why: Every Examples frame on an API page was drawn with `title=""`, and
Expressive Code writes a `figcaption.header` for every frame, so each one
carried an empty caption in its markup. A complete example names the file
the reader saves (example_test.go for Go) and should say it is a whole
program; a fragment has no file name and no header.

what:
- Add `exampleFrame`: a whole file (an example with a source URL) takes the
  file its intro tells the reader to save, else its source file's name, and
  is a complete program unless it is a build or manifest file or a help
  page.
- ApiEntry passes the title, the code frame and the program role from it.
- The frame plugin drops the caption of a frame with no file name; a
  terminal's title bar stays.
- Test the helper over the Go model's examples and the markup of titled,
  untitled and terminal frames.
…ards

why: A section index with headed sections, such as the Go examples and MCP
guides indexes, drew its cards above the whole body, so the reader met the
cards before the sentence that says what the section is. Only a body with
no heading put its intro first. The lead always goes above the cards; the
headed sections follow them.

what:
- `introBeforeCards` looks at what stands above the first heading: a lead
  with text and no table or code goes first. A body that opens on a heading,
  table or code keeps its cards above it.
- Add `splitAtFirstHeading`, which cuts the rendered body at its first
  heading and leaves an anchor written above the heading with it.
- Add `SectionBody`, which draws the lead, the cards or compact list, then
  the rest, and takes over the directory markup and its styles from
  DocPage; the body is rendered to a string only when there is a lead.
- Update the section-index and MCP overview tests to the new order.
tony added 17 commits November 18, 2026 18:01
why: The page tests for the named long frames spread the fence attributes
into an object with a `lines` count, which drops their index signature, so
`astro check` rejected `title` and `height` as missing properties.

what:
- Keep the attributes and the line total in separate fields.
why: The design system owner asked that the Japanese font order (record
0052) be guarded by a test that reads the built CSS, not the dev server's.
The order is only visible in the output: the Fonts API writes the hashed
Plex family and the build's fallbacks into an inline style, global.css
points `--font-sans` at it and `:lang(ja)` uses `var(--font-sans)`. The
source test in typesetting.test.ts checks the helper and the rule, not
what the build wrote from them.

what:
- Add `ja-font-stack.test.ts`. It collects the inline styles and linked
  stylesheets of a page, finds the `:lang(ja)` font-family, follows its
  `var()` chain through the root custom properties and asserts the hashed
  Plex family (declared by the page's `@font-face`), then Hiragino Sans,
  Hiragino Kaku Gothic ProN, Yu Gothic UI, Yu Gothic, Meiryo, Noto Sans CJK
  JP and Noto Sans JP, then system-ui, sans-serif and the emoji faces.
- Read the built /ja/ home page in the assembled-site suite, skipped like
  the other assembled suites when nothing is built.
- Add negative controls: a page shaped like the build with the English
  fallbacks, or with generic faces ahead of the Japanese ones, must fail
  the same assertion; the built page with the English fallbacks swapped in
  must too. The fixture checks run in every loop.
…ped Go program fence

why: The Go attach-and-send-keys page now caps its whole-program fence with
height="24" (record 0027: authors set caps), so the negative case that
renames that fence's file no longer found its text and the negative run
failed with "the page no longer contains" before checking anything.

what:
- The "Go file inclusion missing from the example cache" case finds and
  replaces the fence with its height="24" attribute
…xample

why: Naming whole-file examples passed `title={undefined}` for every other
example. Without a title, Expressive Code reads a leading comment such as
Swift's `// swift-tools-version: 6.2` as the file name and removes it from
the code, so the copied Package.swift no longer matched its native receipt
(check-clipboard failed #334's browser matrix on Server/Package.swift).

what:
- An example without a file name passes title="" again, as before step 4;
  the frame still draws no empty header
- Tests: an untitled frame keeps the leading comment in the code it copies,
  and the control without a title loses it
…reply controls

why: The controls in the reply tests stand for a recording made before
replies were stored: Go's closes on the answer derived from its panes
and Julia's, which has none to derive, does not close. The helper kept
the reply a recording file holds, so the Julia control fails as soon as
Julia's recording stores one, and Go's control would no longer test the
derived answer.

what:
- Drop the stored `reply` from the recording the helper builds unless
  the test passes its own text
why: Go's recording had no `reply`, so its replay closed on an answer
derived from pane output. The generator now stores the example's reply
once the session printed every value it quotes. The recording was made
on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Go server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form
…sing reply

why: The TypeScript recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the TypeScript server again at the revision its protocol
  snapshot names, with the example's reply: pytest printed "2 passed",
  checks.log ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form
… reply

why: The Python recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Python server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the session timestamp, the pane's tty and
  pid, and the elapsed time are this run's
… reply

why: Ruby's recording had no `reply`, and its replay ended on its last
call: the results of tmux_wait are not read as a pane's output, so there
was no answer to derive. The generator now stores the example's reply
once the session printed every value it quotes. The recording was made
on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Ruby server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the server's process id, start time, capture
  ids and timings are this run's
…ng reply

why: Julia's recording had no `reply`, and its replay ended on its last
call: the results of send_keys_and_wait are not read as a pane's output,
so there was no answer to derive. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Julia server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form
…eply

why: The C++ recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the C++ server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the pane's process id and the pytest timing
  are this run's
… reply

why: The C# recording had no `reply`, so its replay closed on an answer
derived from pane output. The generator now stores the example's reply
once the session printed every value it quotes. The recording was made
on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the C# server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the pytest and call timings are this run's
…ng reply

why: The Swift recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Swift server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the session's creation time and reference
  are this run's, and the server orders the keys of its JSON objects
  differently on each run
… reply

why: The Java recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Java server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form; the call timings are this run's
…eply

why: The Rust recording had no `reply`, so its replay closed on an
answer derived from pane output. The generator now stores the example's
reply once the session printed every value it quotes. The recording was
made on tmux 3.7c, a released version; the previous one came from an
unreleased tmux 3.8a build that reports layouts as V2 JSON.

what:
- Record the Rust server again at the revision its protocol snapshot
  names, with the example's reply: pytest printed "2 passed", checks.log
  ends with "checks finished", and the session was removed
- Store tmux 3.7c in the sandbox record, and the layouts it reports in
  the classic string form
)

why: #333 landed on main as a626ef8 while this branch was in review.
The design owner asked for design-tokens.test.ts to run against this
branch merged onto that main before it merges, and the docs test should
run on the combined tree.

what:
- Take main at a626ef8: port picker rows show the API they matched,
  and touch screens get 44px tap targets
- No conflicts; the tree equals git merge-tree of main and this branch
…t a step

why: Design record 0074 sets how the agent's closing reply shows: the
chat's last turn, labelled Agent, in people's type (the prompt's size and
body weight, inline code in mono, paragraphs and inline code only), and
never a step: no tool, tier, arguments, result or pin, no mark on the
rail, and the step count unchanged. The reply turn carried a pin button
for the final state, pinning the last call also marked it pinned, and
its words were set at the captions' smaller size.

what:
- The reply turn has no pin button; only calls have one, and pinning the
  last call no longer marks the reply
- replyParagraphs reads the reply into paragraphs of plain words,
  `inline code` and the printed output it quotes (still drawn as <q>)
- The reply's paragraphs take the prompt's 0.9375rem at weight 400, with
  inline code in the mono face
- Tests: the reply turn's anatomy, rail marks and count, when it shows,
  the pinned state, its type, and the paragraph reader
tony added 8 commits November 18, 2026 22:52
why: The design owner added to record 0074 that output quoted in the
closing reply is drawn as <samp> in mono, without quotation marks. The
generator refuses any quote the session never printed, so each quoted
run is verified terminal output, and output is mono everywhere else on
the site (records 0024 and 0031). <q> set it as a quotation in the sans
face.

what:
- Quoted runs in the reply, and the line the derived answer quotes, are
  <samp>, set in mono like inline code
- replyParagraphs names the run kind output; backtick runs stay code
- Tests expect <samp> and no <q> in the closing turn
why: Record 0074 now says a replay shows only what was recorded. For a
recording with no stored reply, the page built a closing turn labelled
Agent from the last line of each command's pane output: words the agent
never said, which breaks the same never-guessed rule as Wraps (record
0053). All ten recordings carry a reply now, so the site is unchanged.

what:
- A recording without a reply draws no closing turn; the last call ends
  the chat
- Remove the derived answers from the recording model, with runAnswers
  and lastOutputLine
- Tests: no closing turn and no "printed" words without a reply (Go and
  Julia), with a stored reply as the control; the recorded-output check
  reads the calls' results
why: The Raku examples guide the site serves still told a reader to run
`raku -I. examples/NAME.raku` from a repository checkout and ended on a
paragraph about the example check and LIBTMUX_TEST_TMUX, a variable only
the repository's tests set. libtmux-raku PR #32 rewrites the guide for a
reader who installed the library, and the committed model, guide cache and
manifest still described cce868d81. The pin is the merge commit of the PR,
which is on master.

what:
- Pin Raku to libtmux/libtmux-raku@d26f34d42 and regenerate its model and
  path data (exported with Rakudo 2026.09, the compiler recorded in the
  previous model; the exporter bytes are unchanged), tmux usage, source
  cache, guide cache and manifest packages with the repository's
  generators; the mention index, the example sources and the sidebar
  sidecar come out unchanged
- Adopt the source change between the pins: lib/ is untouched, so the
  model keeps 1069 symbols with none added or removed and no doc changed.
  Only the recorded digests of examples/batch-recovery.raku and
  examples/session-workflow.raku move, and the path list gains
  scripts/lib/Scripts/Processes.rakumod, the helper the example check now
  uses to fail an example that leaves a process running
- Take the rewritten examples guide into the guide cache: the guide
  installs LibTmux from zef with tmux 3.3a or newer on PATH, runs each
  program as `raku NAME.raku`, and no longer ends on the CI paragraph or
  names LIBTMUX_TEST_TMUX; session-workflow.raku and batch-recovery.raku
  now print `Stopped the tmux server and removed its socket` in place of
  their /proc cleanup check, and the README's batch recovery program
  follows the same change
- Keep every reviewed tmux usage claim: lib/ did not move, so no evidence
  line moved and only the usage file's revision binding changes
- Leave the landing example, its recording and the home fixture at
  9a9838047f15: examples/quickstart.raku is unchanged between that
  revision and the new pin; the two docs-workflow pins between the pins
  (#30, #31) change no documented content

Source refs: libtmux/libtmux-raku master
d26f34d4220941578a83022cc4dcb2288cae2ec8 (#32), previous pin
cce868d81823db54a0d161a94db4d078d09f1861.
…eir function pages

why: libtmux-lisp names a class and a function `session`, and another pair
`window`. The class page is `libtmux-session-type` and the function page
`libtmux-session-function`; a bare `libtmux:window` links to the class, so a
capability directory spells the accessor `libtmux:window/function`. The chip
drops the suffix from its label, which leaves its link as the only thing that
tells the two pages apart. A chip on the Pane page that reached the Window
class would send the reader to the wrong page and nothing would show it. The
Session, Window and Pane directories that libtmux-lisp#28 adds are the first
to carry these references.

what:
- Add site/test/lisp-function-chips.test.ts, which builds a small
  libtmux.lisp.api/1 export with the same id and slug shapes as the real one
  and asserts that `libtmux:session/function` and `libtmux:window/function`
  chips link to the `-function` pages from the Session, Window and Pane
  pages, that the bare name still links to the class, that the written form
  stays the bare name, and that every reference of a folded directory links
  to the page of the symbol it names
- Read no committed model, so the test holds before and after a Common Lisp
  pin
…bility directories

why: The Common Lisp reference pages for the Session, Window and Pane classes
cannot show the "What is on here" capability directory until the model carries
the prose it is built from. libtmux-lisp#28 adds the three directories and
#29 makes the shipped examples start the tmux on PATH, so the guides and
examples the site quotes changed with it. Both are on master as merge commits,
so the revision stays reachable. The committed model, guide cache and manifest
still described a29c6b96e, the head of the client directory pull request.

what:
- Pin Common Lisp to libtmux/libtmux-lisp@9f364931a and regenerate its model
  and path data (exported with SBCL 2.6.10 and ASDF 3.3.7, the runtime
  recorded in the previous model, from a clean clone with the locked
  dependencies), tmux usage, source cache, guide cache, manifest packages and
  cached examples with the repository's generators; the mention index and the
  sidebar sidecar come out unchanged
- Adopt the source change between the pins: the model keeps 293 symbols with
  none added or removed. The Session, Window and Pane classes gain the
  directory, 9 rows each, and 25 declarations move to new lines because
  model.lisp grew above them; the exporter digest and four of its 55 native
  inputs (libtmux.asd, src/model.lisp, src/options-catalog.lisp,
  tools/documentation.lisp) are the only other model differences. #29 changes
  no file under src/
- Keep every reviewed tmux usage claim: all of them hold at the new revision,
  so only the usage file's revision binding changes
- Take the five changed guides into the guide cache: the README, the REPL
  tutorial, the verification guide and the two workspace guides now run
  programs with `sbcl --script` where they ran `tools/lisp.sh`, the tutorial
  worker is worker.lisp, the workspace command is tools/workspace-cli.lisp,
  which replaces bin/libtmux-workspace, and the tutorial runner starts the
  tmux on PATH instead of offering another binary
- Move the workspace example cached for the landing page to the new revision;
  its bytes are unchanged
- Link all eleven files of the examples index at the new revision, name
  worker.lisp for the tutorial worker, run the sample with `sbcl --script`
  and describe the quickstart as starting its own isolated daemon, which it
  does now that it no longer reads a socket from the environment; the index
  still has seven programs and four support files
- Expect the directories of Session (9 rows, 54 references), Window (9, 55)
  and Pane (9, 58) in the directory test
- Not changed here: the Workspace page, the inventory entry and the source
  link for the workspace command still name tools/lisp.sh and
  bin/libtmux-workspace, which the source no longer has, so the manifest
  reader no longer records the script unit
- Leave the landing quickstart and the Core player recording at the revision
  where they were recorded: they still show the socket-from-environment
  program, and re-recording the quickstart is a separate step

Source refs: libtmux/libtmux-lisp master
9f364931a38fafce7bfea7cb4f7e6b32ef49ebb4 (#28 and #29), previous pin
a29c6b96e1c78501dff5073b538ae3180b0e63e3; merge commits at
libtmux/libtmux-lisp@e3c5380
and
libtmux/libtmux-lisp@9f36493.
…ce link at tools/workspace-cli.lisp

why: libtmux-lisp's support scripts were ported to Common Lisp (libtmux-lisp
dce2b87, "Port the support scripts to Common Lisp"), which removed both
tools/lisp.sh and bin/libtmux-workspace. The workspace command is now
`sbcl --script tools/workspace-cli.lisp`, and with no arguments it prints its
command grammar and exits 2, because the sbcl launcher answers `--help` itself.
After the pin to 9f364931a the Workspace page, the product notice, the
inventory entry and the header's source link still named the two removed
files, and the manifest reader no longer recorded the script unit, so the
inventory test stopped holding that entry to the manifest without saying so.

what:
- Run the command as `mise exec -- sbcl --script tools/workspace-cli.lisp` on
  the Workspace page, with the no-argument form in place of `-h`, and in the
  port's workspaceCli, its package's executable and the inventory
  coordinate; the notice for a checkout now says "Run
  `sbcl --script tools/workspace-cli.lisp`" instead of naming a launcher
- Link the header's `libtmux-workspace` source row to
  tools/workspace-cli.lisp on master instead of bin/libtmux-workspace
- Read the script unit from tools/workspace-cli.lisp in the Lisp manifest
  reader, which restores `script libtmux-workspace` in manifest-packages.json
  and puts the inventory entry back under the two-sided units test
- Replace the destination evidence for the old link with a record for the new
  one, made by scripts/verify-destinations.mjs against a Lisp-only inventory:
  GET https://github.com/libtmux/libtmux-lisp/blob/master/tools/workspace-cli.lisp
  answered 200, checked 2026-11-19; the other records are untouched
- Move the manifest reader test and the header link fixture to the new path

Source refs: libtmux/libtmux-lisp master
9f364931a38fafce7bfea7cb4f7e6b32ef49ebb4; removal in
libtmux/libtmux-lisp@dce2b87.
… and re-record it

why: The landing page program and its Core player recording were the
quickstart at libtmux-lisp 99874b44d, which reads LIBTMUX_SOURCE,
LIBTMUX_PROGRAM and LIBTMUX_EXAMPLE_SOCKET, loads libtmux.asd itself and
connects to a server the page's own setup command starts. At 9f364931a
(libtmux-lisp#29) examples/quickstart.lisp loads tools/load.lisp, starts the
daemon it uses with `libtmux:with-daemon` and stops it by its process id, so
a reader needs no variable, no socket and no tmux command of their own. The
recorder's step map described the older program: it expected a running server
before the first call and a `kill-server` at the end.

what:
- Move the landing example to libtmux/libtmux-lisp@9f364931a (tree 3b1f1d14f).
  The program is the committed examples/quickstart.lisp, except that its two
  lines of 82 and 95 columns are wrapped, because every view of a landing
  program must fit 80 columns; the page's file is 52 lines
- Rebuild the views: concise and errors are the program without its closing
  `pending-daemon-cleanups` assertion, and cleanup is the whole program. Say
  in the page's notes that `observed-value` already unwraps a failed
  observation and that `with-daemon` stops the daemon and removes its socket
  directory on every exit
- Replace the commands: fetch the checkout at that revision and install its
  toolchain, then `cd source` and `mise exec -- sbcl --script
  examples/quickstart.lisp`; the page no longer starts a server or exports a
  variable
- Recorder: a recipe may list `inPlaceFirst`, the flags that begin an
  invocation the shim runs as tmux itself untraced. libtmux-lisp starts its
  daemon as `tmux -D -f /dev/null -S <socket>`, which ends in a path that
  differs on every run, so `inPlace` (the last word) cannot name it, and a
  wrapper process in between would make the daemon a stranger to the library
  that stops it by process id
- Lisp recipe: drop the setup that started the server, run the program from a
  directory that links the checkout's tools/ and holds the displayed copy, give
  it a TMPDIR of its own where the recorder looks for the daemon's socket
  (`libtmux-lisp-daemon-<six characters>`), put the pinned asdf.lisp first on
  PATH so a mise shim of the same name is not read as ASDF, and map the calls
  of the new program: the daemon's startup probes belong to the first call,
  the pure reads of its two-call line to one step, and `with-daemon` ends the
  run with a `stop-daemon` step on the `(daemon)` line, which stops the server
  and sends no command
- Re-record the Core player at 9f364931a on tmux 3.7c: 15 steps, printed
  output equal to the page's, `--check` passing on tmux 3.7c and 3.3a
- Record the verification of the new program in the home fixture: digests of
  the four views, the source tree and the commands, run on tmux 3.3a, 3.7c
  and 3.8. check-example-prose.py cannot run this program, because the PATH
  shim it puts first is a script and libtmux-lisp refuses a script as the
  daemon's program; each of the 12 runs (four views on three versions)
  executed the page's two commands with the displayed view written over the
  checkout's file, a private TMPDIR, and then required the four printed lines,
  exit status 0, no daemon process and no file left
- Update the recipe and recording tests to the new program, and move the test
  of the player's "server is running" note to the Haskell recording, the only
  other one that starts with a server
- Not changed here: the Capture pane output example and the attaching guide
  still read LIBTMUX_PROGRAM to choose a tmux binary

Source ref: libtmux/libtmux-lisp master
9f364931a38fafce7bfea7cb4f7e6b32ef49ebb4 (#29), previous landing revision
99874b44dbe29b3651597a5debbacccde235d96c.
…ault tmux

why: Capture pane output and Attaching to tmux told a reader to set
LIBTMUX_PROGRAM to choose a tmux binary. That variable is the libtmux-lisp
repository's example-runner setting and means nothing to a reader. Since
libtmux-lisp#29 (9f364931a) the shipped programs stop reading it and run the
`tmux` on PATH, which is also what `open-client` uses when `:program` is
omitted; 0f9da93, the revision both pages run, already has that default.

what:
- capture.lisp: drop the `program` binding and `:program`; the pane signals
  its `wait-for` channel with plain `tmux` instead of a CAPTURE_TMUX
  variable, because the pane inherits the program's PATH
- connect.lisp: drop `*program*` and both `:program` arguments
- Replace the sentences that named the variable with "The program runs the
  `tmux` on your `PATH`", and say why the pane's `tmux` is the one the
  program started
- Update the displayed-program digests, the tmux versions and the
  verification checks in capture-examples.json and attach-examples.json;
  the pinned revision and the setup commands do not change
- Not changed: the program's own `LIBTMUX_SOCKET_PATH` input in the attach
  guide, which is a documented input of the displayed program

Verification: check-example-prose.py --example capture and --example attach
(--port lisp) ran each page's displayed setup and program at 0f9da93 on tmux
3.3a, 3.7c and 3.8, with a symlink to that build first on PATH. All six runs
exited 0, printed `libtmux capture ready` or `work`, and left no
/tmp/libtmux-lisp-* directory or tmux server. A probe copy of capture.lisp
printed the pane's resolved `tmux` as the selected build on each version; the
attach guide's borrowed-server path printed `work`, left the server running
and exited 0 on each version. The focused vitest files and
check-example-blocks and check-example-indentation passed.

Source ref: libtmux/libtmux-lisp master
9f364931a38fafce7bfea7cb4f7e6b32ef49ebb4 (#29).
@tony
tony deployed to docs-preview November 19, 2026 13:21 — with GitHub Actions Active

This branch was successfully deployed

1 active deployment
docs-preview — f4963400 Deployed Nov 19, 2026 by tony via publish-preview / publish #1503
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