Cover port-only build failures and refresh the new-port pages by tony · Pull Request #301 · libtmux/docs

tony · 2026-11-11T01:27:40Z

Summary

Fix four classes of failure that appeared only when a port built its docs, never in docs CI.
Add a weekly port-heads workflow that builds every port's head against docs main through port-docs.yml.
Locate tmux-usage citations by their text, so a port edit above a cited line no longer breaks its docs build.
Bring the Haskell, OCaml, Clojure, Erlang, Lisp and Perl pages up to each port's current source.
Remove two 5-second test timeouts that flaked docs CI.

Changes by area

Port-build coverage

scripts/lib/port-checkout.mjs: one checkout resolver for every script; a wrapper such as clojure derives its parent's checkout (java) from its own.
scripts/check-port-badges.mjs: fails on any README badge badges.mjs cannot map, naming the port and URL.
.github/workflows/port-heads.yml: weekly and on dispatch, one leg per port family, publish: false; lua and ruby run their own exporter steps.
port-docs.yml: new optional input source-repository (default: the caller's repository), so a docs-repo caller can build another repository; every port caller is unchanged.

Citations

scripts/lib/tmux-usage-locate.mjs: finds each rule's cited line by its has text within its in/within body; a stored line only breaks ties between duplicates.
scripts/tmux-usage/claims.json: 5065 of 5195 citations no longer pin a line; go and java claims re-cited to where their commands are built now.

Port pages

Haskell (haskell(feat[docs]) Document capture, queries and native examples #293, Document checked Haskell mutations and refreshed observations #300): capture, queries and mutations at native 00b47e6, a real-tmux homepage program, 16 public modules, an examples index of the six tested programs, and a workspace page that describes the core as it is.
OCaml (Add OCaml workspace interruption guidance after the release #294, Verify OCaml variant constructor destinations #295): workspace recovery guide, constructor parsing, and an examples index of the 20 tested programs.
Clojure (fix(api-model) Keep Clojure signature bindings local #299): Clojure call names and locals no longer link to Java methods; the landing page says the port connects to servers and labels captures and errors as plain maps and ex-info.
Erlang: the landing program is the tested with_owned form, and the workspace page describes plan, apply and the escript, and says the escript is not published to a registry.
Lisp: the owned-workspace guide is the primary workspace guide; the workspace page covers inspect and --reconcile and tells the reader to run bin/libtmux-workspace from a source checkout.
Perl: the examples index lists all six tested programs.

Tests

site/test/install-widgets.test.ts: the Python picker test stubs highlighting it never asserts on.
packages/api-model/test/resolver-corpus.outer.test.ts: an explicit 20-second budget for the corpus-wide parse.
site/test/product-docs.test.ts: a workspace CLI with a launcher (workspaceCliRun) expects the "run from a source checkout" sentence.

Test plan

Every --check generator and gen-tmux-usage --check --source for all 22 ports reproduce the committed data
gen-tmux-usage --ports clojure passes against libtmux-java's Frame MCP and workspace companions as concept examples #143 head, which fails on main
port-heads built every leg on GitHub; all passed except haskell, whose exporter gap this branch's Document checked Haskell mutations and refreshed observations #300 fixes
astro check with no errors; theme and api-model suites
Full CI

why: Workspace callers need a complete interruption example with retained evidence, compensation limits and navigation from task pages. what: - Add the source-owned workspace recovery route and overview links - Refresh native contracts, guide bodies, source links and mentions - Preserve partial qualification and unresolved streaming results Native source: 3be232388ec28a260bb87c20e410af2dfa7b1fa2

why: Revision-bound package and example catalogs must describe the same native source as the refreshed API model and guides. what: - Regenerate the OCaml manifest inventory at the selected source - Align embedded example provenance without changing source bytes - Preserve every sibling catalog entry

why: Constructor links need declaration evidence for their names and parent types rather than a manually approved heading. what: - Read constructor anchors and validate their type, class and name. - Reject markers inside quoted attributes and comments. - Record Option.None's identity and remove its manual review row. - Cover constructor declarations and mismatched markup.

why: The constructor destination fix requires verification on the published shared-docs baseline. what: - Merge main with the released navigation and OCaml producer fixes.

why: The interruption guide needs public contracts, examples and source citations from one native revision. The released builder validates its compiled inputs and native exporter separately. what: - Integrate the released docs baseline without rewriting branch history - Regenerate OCaml API, guide, example and package provenance - Keep recovery navigation and unresolved qualification limits

why: Shared documentation needs the public record owners and actual defining sources while retaining native Haskell signatures. what: - Add a separate observation profile for the scoped Server and snapshots - Preserve module reexports and owner-scoped record fields - Validate compiled exports, native anchors and archived source text - Retain native inputs and preserve the qualified scalar profile

why: Duplicate record labels and facade reexports need their public context without changing native names or losing defining sources. what: - Adapt the qualified observation profile alongside scalar interfaces - Retain record owners, native links and ordered module reexports - Give the reexport root one navigation row without copied members - Reject incomplete modules and conflicting module identities

why: Public capture and recovery types need readable continuation lines within the API reference column limit. what: - Continue outer type arrows while preserving native links and tokens - Keep callback scopes, character literals and escaped strings intact - Leave unbreakable literals exact and report their width

why: The public observation API needs native reference ownership, checked source provenance and guides that use the same reviewed library revision. what: - Publish the Haddock observation model and authored navigation groups. - Stage capture, offline-fixture and performance guides from source. - Bind native command attribution to reviewed source and API metadata. - Exercise snapshot collection ordering and preserve excluded products.

why: Function and type references need declaration-level destinations so readers reach the named API with the correct language kind. what: - Resolve unique public labels within their declared module. - Prefer data heads for shared type and constructor spellings. - Preserve ambiguous labels and explicit source-fragment destinations.

why: Compiler extension references need checked destination identity alongside the package API links. what: - Record the owning GHC manual heading for record-dot syntax. - Capture the successful destination response and identity evidence.

why: The capture API adds an entry module and reverse references beyond the scalar API. Reference checks need to preserve that native structure. what: - Derive module sections from the current public model in its declared order. - Compare exported members within their own sections, excluding backlinks.

why: The capture reference now resolves more native cross-references. Preserve that coverage as the public API grows. what: - Raise the Haskell-only resolved-link floor from 300 to 1372. - Keep the unresolved-type ceiling at zero and other ports unchanged.

why: The public Runtime API needs reference pages and an installed guide that agree with the source consumers can build. what: - Refresh the native Haddock profile while retaining separate exporter provenance - Stage the shared Runtime guide and preserve every existing public signature - Bind queued command evidence and reference fixtures to the selected source

why: Shared Runtime declarations add native links that the reference regression check must retain. what: - Raise only Haskell's floor from the complete rendered reference - Keep the unresolved-type ceiling and other port baselines unchanged

why: The exact guide-path fixture omitted the shared Runtime page and rejected the complete public guide catalogue in CI. what: - Include the shared Runtime source and reader route in the guide contract

why: The shared reference must preserve the current public query types and field modules alongside detached snapshots, without exposing implementation APIs. what: - Qualify the sixteen-module query profile and its defining source inventory - Preserve opaque type parameters, constrained signatures and native default sections - Retain honest file-level source links for ambiguous native identifiers - Compare native source pages with the merged source and retain compiler fixtures - Preserve the scalar and observation profiles and their validation checks

why: Parameterized query declarations need source-bound evidence through the shared adapter, not assumptions carried over from scalar and observation models. what: - Record the isolated native export and its committed producer separately - Retain native signature and defining-source fidelity through normalization - Check opaque query parameters, field ownership and public reference navigation - Reject unsupported profiles and declaration forms before rendering

why: Whole native fixture and cross-port manifest audits need the outer tier; fast adapter and route checks should retain their shorter development loop. what: - Classify the complete Python native audit as an outer subprocess check - Bound that case independently inside the unchanged outer-loop budget - Move the complete reference manifest assertions into a dedicated outer suite - Preserve all route, native provenance and cross-port assertions

why: Reference pages, reader guides and command attribution must describe the same merged public source and preserve its typed query contracts. what: - Regenerate the current observation and query model with native provenance - Stage the query guide alongside capture, fixtures and shared Runtime scopes - Qualify capture and query-fetch command paths against the complete source - Keep relationship tokens distinct from commands that change window links - Validate declaration heads before matching their type parameters

why: Readers need to see the implemented client observe tmux, select panes and handle errors rather than only construct scalar values. what: - Reuse the native query program with complete private-server setup and teardown - Show physical and contextual selection, cardinality and application errors - Bind standalone Cabal inputs, expected output and copied programs to the source - Replace the core copy and link capture, snapshot, query and fixture modules - Resolve the program's public API links without requiring extra showcase panels

why: A pasted recipe must stop its owned server without replacing the caller shell exit handler. what: - Run setup, the native query program and teardown in one subshell - Check cleanup before the caller exits and preserve its existing trap - Keep the displayed recipe and execution record identical

why: The expanded reference needs complete native rendering checks and a subprocess deadline that can stop a stalled audit. what: - Update signature, link and semantic-kind coverage for the current native artifact - Keep every declaration and constructor rendering assertion - Bound the Python fixture process within its outer test deadline

…#293) what: - Include the current shared landing layout, capability-panel and badge fixes - Retain the real-tmux Haskell homepage, public API links and reference qualification - Carry the current build checkout handling from the shared site why: - Validate the refreshed Haskell docs against the current shared site - Preserve the committed exporter identity already recorded by the native artifacts

why: The query guide names Natural, which belongs to base rather than the libtmux declaration catalog. what: - Link the documented bound to its verified Numeric.Natural declaration - Check native type resolution without claiming the name in other ports - Regenerate the mention index after resolving the guide reference

…cessor why: Core home entries describe either objects or modules, so their shared type does not expose a lead field. what: - Check the rendered Haskell lead through the existing coreLead accessor - Preserve the content assertion while satisfying both entry variants

why: A long Haskell program expanded the grid beyond the phone viewport, and nested setup blocks inherited the showcase fixed height. what: - Give the program grid a column that can shrink to the available width - Restrict showcase sizing to its direct program block - Let setup, package files and expected output retain their natural heights

why: Installation cards and copied agent prompts still described the scalar bootstrap and falsely required exact compiler tool patches. what: - Lead with the public LibTmux facade, detached graphs and typed queries - Select compatible tools from the manifest and state the native host requirements - Run the owned capture/query example while preserving the boundary around unfinished automation

why: The rendered public query surface resolves more references than the observation-only profile, so the existing floor would permit a regression. what: - Raise only the Haskell cross-reference floor from the measured selected-source build - Keep its unresolved-type ceiling at zero and every other port baseline unchanged

…scription why: The root solution card depended on the old values-only execution profile, and package discovery still listed only scalar modules. what: - Select module-home descriptions from the core metadata independently of example execution - List the public facade, capture, snapshot, query and fixture entry points - Check the root Haskell card against capture and detached-query behavior

…mand why: Clojure prose such as `new-session!` and `send-keys!` linked to the tmux manual pages for new-session and send-keys. The trailing ! belongs to the Clojure function name, so the reader landed on a command that takes a different shape of input instead of the library reference. what: - Skip a tmux command match inside a code span when ! or ? follows it directly; the span then links to the port's reference page - Test that `new-session!` and `send-keys!` link to the Clojure reference while `tmux new-session` still links to the manual

…t one why: The Clojure landing page listed "Connect to or start a tmux server" and described the library as able to "connect to and create servers", both mapped to open!. At the pinned revision open! requires an explicit :socket-path or :socket-name and returns a client; nothing in libtmux.core starts a server, and the start! function that would is not merged. Its core page also lacked the MCP statement. what: - Add a "connect" capability (Connect to a running tmux server) backed by the same open! symbol and map clojure to it instead of "servers" - Reword the clojure core description and say the port ships no MCP server - Test that clojure keeps neither claim

…ild mise why: The Lisp workspace overview said "Build `mise` from the source revision in the installation guide". mise is the toolchain launcher that workspaceCli names first, and the CLI is a shell script in the checkout (bin/libtmux-workspace running tools/workspace-cli.lisp), so nothing is built and the sentence pointed at the wrong program. what: - Add workspaceCliRun for ports whose launch command starts with a tool runner; the notice names it and says to run it from a source checkout - Set it to bin/libtmux-workspace for lisp; other ports are unchanged - Test the Lisp notice text and relax the product-docs executable check

…t tree why: check-source-links.mjs now imports scripts/lib/commit-on-host.mjs, and the audit test runs a copied script tree, so every case failed with ERR_MODULE_NOT_FOUND in PR #301's CI. what: - Add scripts/lib/commit-on-host.mjs to the files the test copies

why: Fix the docs findings the six new-port adoption reviews recorded (llms.txt descriptions, examples indexes, guide cards, the MCP line, stale Clojure and Lisp claims) in the same wave.

…index why: The Haskell port had no examples index, so its six tested programs were reachable only through guide links. Erlang, Lisp, Clojure and Perl got an index listing every program and linking its source. what: - Add ports/haskell/examples/index.md with each program, what it demonstrates and its guide, linking the source at the API model revision 00b47e6d94b1 - Test that the index lists six source links at the model revision

…es only why: The workspace availability page said the public core provides typed IDs, dimensions and version admission, and sent readers to the typed values example. The port at 00b47e6d94b1 also captures server state, runs typed queries and renames sessions, windows and pane titles. what: - State the capture, query and rename capabilities and the missing creation, input and event streams a workspace manager needs - Link the examples index instead of the typed values guide - The statement that no workspace package exists is unchanged

why: The OCaml examples index carried four cards and listed none of the 20 programs under examples/, while Erlang, Lisp and Clojure list every program. what: - Group the 20 programs into five tasks, each with what it demonstrates, its guide and a source link at the API model revision 205dfda49742 - Test that the index lists 20 source links at the model revision

…x-info why: The landing page claimed "Typed objects instead of parsed format strings" and "Typed errors instead of exit codes and stderr" for Clojure. At libtmux-java a0ecbc16 (clojure 941f2162) captured values are plain maps and failures are `ex-info` exceptions carrying classified `:tmux/error` data that `libtmux.core/error-summary` extracts. Those labels were shared by every port. what: - Add an optional per-port `capabilityLabels` override to core-home entries - Set the Clojure `objects` and `errors` labels to what the API offers - Test that the Clojure labels no longer say typed objects or typed errors

why: The assembled product check requires an unpublished product page to say so in the words it matches, and the rewritten Erlang page said "No registry package is published", which it does not. what: - Say the escript is not published to a registry

why: A port whose workspace CLI starts a launcher now gets "Run X from a source checkout; the installation guide lists the setup." from workspaceOverviewNotice, but the assembled check still required the build sentence, so Common Lisp failed it. what: - Expect the run sentence when workspaceCliRun is set, the build sentence otherwise

why: The new-port sweep ledgers queued four docs fixes for this wave: missing examples indexes for Haskell and OCaml, a Haskell workspace page that described the core as typed values only, and Clojure core-home labels that described Java behaviour. what: - Haskell and OCaml examples indexes, each linking its tested programs at the source revision the site publishes - Haskell workspace page: capture, typed queries and renames, and what is still missing - Optional per-port capabilityLabels in core-home, used by Clojure for plain maps and ex-info failures

…break why: The Erlang workspace page wraps "It is not" and "published" onto two source lines. Markdown keeps the soft break as a newline in textContent, so the single-space pattern missed a page that does say it is not published (CI run 42962191558). what: - Accept any whitespace between "not"/"no" and "published"

why: The front page showed a long port-specific sentence on the Haskell Core Library card where every other language says "Control tmux from your code.", and the example note under the Haskell program described error handling instead of how to run it. what: - HomeIntro.astro: every Core card shows the shared description - home-examples.json: the Haskell note says the run command starts and stops a private demo server - home-launcher.test.ts: every Core card carries the same one line

why: The Core Library page spent its opening on window-link details, snapshot retention and an MCP aside, and a landing card pointed readers at entity IDs and dimensions before the client itself. what: - Open with Server, capture, records and the rename and title edits in four lines, and say that session creation and input are in development - Drop the typed-values card from the landing page; the guide stays in the guide list - Drop the MCP sentence

why: The sentence about the Python MCP server pulled readers of the Erlang, Lisp, Perl and OCaml Core Library pages away from the library they came for; the product picker already shows that these ports have no MCP server. what: - Remove the sentence from the erlang, lisp and perl landing pages - Keep OCaml's package sentence and drop its MCP clause

…319c42 why: Repinning the Lisp model to e6f319c42 (88d1686) added 52 public symbols. Their signatures carry more Lisp default forms, and the reference draws a default through the type renderer, so each symbol in a default counts as a plain type name. CI run 42979367329 measured 99 against the ceiling of 70: t 35 and nil 30 (the model's t and nil defaults went 32 -> 35 and 22 -> 30), client 9 and quote 8 (eight (slot-value client (quote ...)) defaults), name 4. what: - Record lisp at 99 in type-links-ceiling.json

… page why: The rewritten Haskell Core landing page (070510d) names `Server`, which resolves to LibTmux.Server, so gen-mentions --check failed in CI run 43002531136 with the index stale. what: - Add the one mention of LibTmux.Server#t:Server on /haskell/latest/core/, in the generator's port, symbol, page order

why: d55b950 removed the Python MCP server sentence from the Erlang, Lisp, Perl and OCaml landing pages as a distraction from the library; Clojure kept the same sentence from 7a58018. what: - Remove the sentence from the Clojure Core Library page

tony added 30 commits November 8, 2026 23:22

chore(site[ocaml]) Sync the released docs baseline

a6575b8

why: The constructor destination fix requires verification on the published shared-docs baseline. what: - Merge main with the released navigation and OCaml producer fixes.

haskell(test[guides]) Include shared Runtime in reader paths

60a740b

why: The exact guide-path fixture omitted the shared Runtime page and rejected the complete public guide catalogue in CI. what: - Include the shared Runtime source and reader route in the guide contract

tony added 17 commits November 10, 2026 19:49

Merge branch 'fix/r21-docs-findings'

96b0f7a

why: Fix the docs findings the six new-port adoption reviews recorded (llms.txt descriptions, examples indexes, guide cards, the MCP line, stale Clojure and Lisp claims) in the same wave.

tony force-pushed the release/r21 branch from a1e58b4 to 4cc407d Compare November 11, 2026 10:18

tony added 2 commits November 11, 2026 04:25

tony temporarily deployed to docs-preview November 11, 2026 13:25 — with GitHub Actions Inactive

tony merged commit cfa8a14 into main Nov 11, 2026
3 checks passed

tony temporarily deployed to docs-preview-cleanup November 11, 2026 22:49 — with GitHub Actions Inactive

Navigation Menu

Repository navigation

Cover port-only build failures and refresh the new-port pages - #301

Cover port-only build failures and refresh the new-port pages#301
tony merged 96 commits into
mainfrom
release/r21

tony commented Nov 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

tony commented Nov 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes by area

Port-build coverage

Citations

Port pages

Tests

Test plan

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

tony commented Nov 11, 2026 •

edited

Loading