GeezerVison

Furo's own search.html needs a JS index this build doesn't serve at
this path; the shell already indexes every port at /search/. Overriding
the search.html template (rather than adding a page) works regardless
of the theme, and the redirect wording matches the existing rediraffe
stubs so scripts/audit-site.mjs's redirect check skips it.

Closes notes/status.md's "Python and C++ are unskinned islands" glitch:
without this file Furo has no --lt-* mapping and paints its own stock
blue. Imports https://libtmux.org/_shell/tokens.css and maps the shared
~25 semantic tokens onto Furo's --color-* contract. The html_css_files
and html_js_files entries wiring it (plus shell.js) into conf.py landed
in 7380cd478 alongside an unrelated search-page fix from concurrent work
in this worktree.

…hable

A var() on an undefined custom property with no fallback resolves to the
guaranteed-invalid value, so every remapped --color-* would compute to
unset until libtmux.org resolves (notes/status.md: never deployed) --
worse than the stock-Furo glitch this adapter exists to close. Fall back
to Furo's own stock color per property instead, so an unreachable
tokens.css degrades to unmodified Furo rather than a broken page.

Pagefind logs a missing html[lang] warning when indexing the assembled
site; the rediraffe-generated stubs in this tree have the same gap, but
there's no reason to match it here too.

An absolute https://libtmux.org/_shell/ URL resolves nowhere until the site
is deployed, so the injected chrome was invisible in every local preview and
the design-token bridge could not be checked at all. A root-relative path
resolves on both the deployed origin and a local preview server.

why: The header cited a checkout path under the author's home
directory as the source of the fallback colours — a tracked file in a
public repository naming a machine only one person has. The rest had
grown past what a reader of this file needs.

what:
- Name the gp-furo-tokens package instead of a local checkout path
- Say which repository the design notes live in, rather than citing
  paths that resolve nowhere from here
- Trim to what the file cannot be read without: the mapping's purpose,
  why every fallback is Furo's own value, and the cascade order

why: The shell integration is correct only where this tree is served
under libtmux.org, at /py/<version>/api/. docs.yml publishes the same
tree to the bucket root behind libtmux.git-pull.com, where /_shell/
holds nothing and /search/ is the page itself — so the override turned
that host's working search into a page that refreshed to itself for
ever, and asked for a shell.js that 404s.

what:
- Gate the search override and shell.js on LIBTMUX_DOCS_STANDALONE,
  on by default for the two consumers that nest the build, and set to
  1 by docs.yml, which does not
- Move the override to _templates_shell so the gate can drop it
  without disturbing the templates gp_sphinx already expects
- Guard the redirect on the page's own path, so a tree served at a
  root cannot refresh to itself even with the gate wrong
- Leave the token adapter on in both: it degrades to stock Furo alone

why: Which of chrome and the search override a build carries decides
whether libtmux.git-pull.com keeps a working search or serves a page
that redirects to itself. Nothing re-ran that check; it was a pair of
builds done by hand, and docs.yml only runs on master, so a wrong gate
would first be seen on the deployed site.

what:
- Read docs/conf.py the way Sphinx does, under both env settings, and
  assert what each resolves templates_path and html_js_files to
- Assert the override sits outside _templates, which the gate cannot
  drop, and that the redirect is guarded on the page's own path
- Both bite: flipping the gate fails four, replacing the guard with a
  bare meta refresh fails the fifth

why: The flag is correct only while this tree is published to a bucket
root. When the sync moves to a per-port prefix under libtmux.org the
build becomes nested and the flag becomes wrong, but nothing said so —
and the failure is quiet: the port publishes with no chrome and the
wrong search, which reads as a broken shell rather than a stale flag.

what:
- Name the condition that retires the flag, and what leaving it does

why: The sync wrote the whole bucket root with --delete, which is the
shape libtmux.org's per-port prefixes exist to prevent, and it left the
Python docs outside the site: every /en/py/<version>/ URL 403s because
no port tree has been published. libtmux/docs is public as of today, so
its reusable deploy workflow can be called from here.

what:
- Split the job: build uploads docs/_build/html, publish calls
  libtmux/docs reusable-deploy.yml and deploys only en/py/latest
- Pass path-prefix unprefixed by locale; the workflow prepends it
- Add the workflow-level concurrency group every caller must set
- Drop LIBTMUX_DOCS_STANDALONE: the tree is nested now, so the shell's
  chrome and site-wide search are reachable and belong on
- Pin the reusable workflow to a commit rather than a moving branch

why: The SHA pin stood in for a tag that did not exist when this was
written; libtmux/docs has since tagged v1, which is the ref its own
header asks callers to use and bump on review.

what:
- Point the publish job at @v1, whose reusable-deploy.yml is
  byte-identical to the commit it replaces

why: The previous shape moved the publish, which would have stopped
libtmux.git-pull.com updating the moment it merged. Serving both costs
one more build and leaves a failure on the new side with no effect on
the old one.

what:
- Build twice: the two sites need different bytes, not one artifact
  published to both. git-pull.com is served at a root and is built
  standalone; libtmux.org nests at en/py/latest and carries the shell
- Publish git-pull.com from inside its own build, exactly as before,
  rather than behind an artifact that would not keep its symlinks
- Give libtmux.org its own LIBTMUX_ORG_* secrets, leaving LIBTMUX_DOCS_*
  meaning what it means today
- Move the paths-filter gate into its own job, so one output feeds both
  and no step repeats the condition
- Pin the shared workflow to v2

why: libtmux/docs deleted v1 and v2, so the `@v2` here resolved to
nothing and this workflow could not have started. Its replacement is a
0.x prerelease series documented as moving, and a ref that can be
repointed changes what executes in this repository — with
`id-token: write` and a role that can write the bucket — without a diff
here or a review.

what:
- Pin the commit the deleted tag pointed at, whose reusable-deploy.yml
  is byte-identical to both deleted tags
- Name the release it belongs to in a trailing comment, which is the
  form Dependabot reads to offer a bump

why: libtmux/docs has settled its convention — callers pin a full-length
commit and name the release beside it — and the commit carrying that is
the one to depend on. Its reusable-deploy.yml differs from the pinned
one in comments only; the parsed workflow is identical.

what:
- Pin e30bcba4, which tag v0.1.0-alpha.1 names
- Correct this comment: it claimed Dependabot would offer the bump, and
  nothing here will, since the repository has no dependabot.yml

/en/py/latest/ 403s on libtmux.org — nothing has published under a port
version prefix. This lets the branch publish without merging, which also
sidesteps the base-branch problem: this PR targets docs-site, so merging
it would trigger nothing.

Repinned to ce9d7ed, which fixes the manifest upsert: jq precedence made
it add an array to an object, so every publish failed after syncing. Found
on the first real run, from libtmux-rs.

libtmux.git-pull.com is unaffected — its leg publishes in the job before.

Drop docs-site-deploy from the trigger when merging to master.

/en/py/latest/ was serving Furo, and /en/py/latest/concepts/ 403'd — so
the port switcher was broken for Python from every shared page.

The libtmux.org leg uploaded docs/_build/html, on the assumption that the
Sphinx site is this port's tree. It is not: en/py/latest/ is the shared
shell rendered with Python's code fences, and the gp-sphinx output belongs
at en/py/latest/api/ inside it. Publishing Sphinx to the prefix replaced
the whole tree, api and all.

That leg now runs libtmux/docs's build-site.sh, which renders the shell
and runs sphinx itself from this checkout, and uploads the assembled
en/py/latest. Without --skip-refs, because Python's api/ is the real
render rather than the redirect stub every other port gets — it is what
check-style-parity.mjs measures against.

libtmux.git-pull.com is untouched: its leg still builds standalone and
publishes in-job, before this one runs.

Both reached the API reference as a name and a base class with no sentence.
One says a primary key was never set; the other that a filter named a lookup
that does not exist, which is what a mistyped keyword arrives as.

It is the default value of every `scope` parameter and appeared in the API
reference as a name with a `...` body. The distinction worth stating is that
it is not the same as passing no scope: tmux resolves the option itself.

why: Port builds still use the previous docs shell.

what:
- Pin the docs checkout and deploy workflow to the published refresh.

why: The branch needs a reviewed, explicit publication path without
merging, while pull requests must remain build-only.

what:
- Call shared source-bound builds with the native Sphinx reference
- Add dispatch inputs and include workflow edits in the path filter
- Keep standalone publication on default-branch pushes
- Group weekly GitHub Actions updates for both shared workflow pins

why: A source revision can carry a lock resolved with a contributor's
package cooldown. A clean runner must reproduce that lock.

what:
- Pin the shared native build and publisher to the same reviewed commit
- Keep standalone Sphinx commands on the committed lock

why: Published port trees need the compact app layout and neutral
reading colors from the merged documentation changes.

what:
- Pin the build and publisher to the same reviewed docs revision
- Include the centered README parser and empty-sidebar layout fixes

why: Ruff rejects the extra blank line after the default-scope class.

what:
- Remove the surplus blank line before DEFAULT_OPTION_SCOPE

why: Publication must reject altered build bytes and dirty source
records before obtaining AWS credentials.

what:
- Pin the builder and publisher together at reviewed revision 843278f5.
- Preserve the standalone site and ordinary dispatch behavior.
- Verify real publication, three pre-AWS rejections, immutable reruns,
  and ordinary public delivery in hosted run 36642578777.

why: Use the selected source and toolchain for the MCP catalog.

what:
- Pin the shared builder and publisher to one reviewed revision

Shared workflow: libtmux/docs@42dd5b7

why: The Python documentation caller needs the same reviewed renderer
and publisher revision used by the other libtmux.org ports.

what:
- Update both reusable workflow pins together.
- Preserve the isolated docs caller and source selection.

validation:
Paired-pin and diff checks pass. Workflow syntax passes with the existing
queue-keyword compatibility exclusion. Library files are unchanged.

why: Python's selected MCP revision groups tool pages in subdirectories,
so publication needs the recursive source validation. The publisher also
accepts the current AWS CLI missing-manifest diagnostic.

what:
- Pin both libtmux.org reusable workflows to the same reviewed revision.
- Keep the standalone Sphinx publisher and library source unchanged.

why: Publish the reviewed reference UI through the owning repository
with an immutable shared builder and publisher revision.

what:
- Bind the docs builder and publisher to the reviewed revision

what:
- Bind the owning docs builder and publisher to the reviewed revision

why:
Deliver the reviewed API navigation, reference previews, initial styling,
and installation controls through the existing publication workflow.

why: Deliver the shared API reference fixes through the owning
documentation publisher.

what:
- Bind the documentation builder and publisher to one revision

what:
- Pin both documentation build and publication to the reviewed shared
  checkpoint.

why:
- Deliver the verified documentation wave through the existing owner
  workflow without changing the library or publication scope.

what:
- Change only the two shared workflow pins to 32de9876ff51cdb206acbb05785f946cc08f517a.

why:
- Publish with the reviewed shared documentation checkpoint.

what:
- Change only the two shared workflow pins to 8f304904465a15b929e139345d9b9e4672ecb7b3.

why:
- Publish with the reviewed shared documentation checkpoint.

what:
- Change only the two shared workflow pins to
  9f5cef954e3c52e7eb239a3da56a34f92b69f161.

why:
- Publish with the reviewed shared documentation checkpoint.

what:
- Add GitHub, package and external documentation menus to the site
  header, each row showing its destination's icon
- Show a parameter's type and optional marker against its name, print an
  overload note as "for <label>" without doubled parentheses, and keep
  the brackets of [source] links outside the link
- Finish page appearance before revealing it, and load pages with
  ordinary document loads instead of the client router
- Upload content-hashed assets before the HTML that names them, keep
  earlier hashes, and cache them as immutable
- Start optional Cloudflare Web Analytics after page load, only where
  the edge grants permission
- Outside Python, present available MCP and workspace companions as
  concept examples
- Wrap Python declarations at the 60-column reference width the way ruff
  format does
- Render a reST rubric with no body as a heading

why: The header carried no repository, package or off-site API reference
links. Only a port's landing and overview pages listed them together,
and every other page offered one footer GitHub link.

Shared source: libtmux/docs
From: 9f5cef954e3c52e7eb239a3da56a34f92b69f161
To:   7ffc04bceec2cada8149a32e46926cba9fa9ecd2

what:
- Draw every API kind mark on one system of six hue families in
  navigation trees, member lists, index cards, search results, hover
  cards and prose links, mark only the first mention of a name in a
  section, and draw modifiers as outlines
- Badge each product in the documentation picker and the solution menu
  with its release stage, or concept for a companion outside Python,
  behind a hover card that links to the support page, and head each
  product in the GitHub and Packages menus with a label
- Browse the tmux options, hooks and format variables of each pinned
  release in a catalog, and link and badge tmux commands, options, hooks
  and formats wherever guides, the manual, API docs and MCP descriptions
  name them
- Show tmux keys as key caps in the manual and guides, and list the CLI
  Manual, the tmux catalog and the C source reference in the tmux
  sidebar
- Link workspace commands, configuration keys, and MCP tool, prompt and
  resource names written in code to their reference rows, resolve Sphinx
  roles in MCP descriptions, and list MCP arguments in the API parameter
  style
- Document type parameters under their own heading with bounds and
  defaults, and link them from signatures, bounds and prose
- Keep the Members heading and the active group heading in view while a
  long member list scrolls
- Move the pages about the site under /meta/ with redirects from the old
  addresses, drop the cross-port /mcp/ overview, and point the header
  MCP chip at the current port's MCP home
- Rebuild the native tmux examples as a short concept and numbered steps
  that lead up to the complete script, each step quoting that script
- Title the home page "libtmux: pilot tmux in your language" and move a
  reference page's qualified name into its Source and package disclosure
- List the parameters of a Python function's implementation instead of
  each overload stub, whether or not a docstring describes them, and
  leave out an undocumented self or cls receiver
- Take the release stage of libtmux, tmuxp and libtmux-mcp from their
  PyPI Development Status classifiers

why: A reference page marked names with a different colour per kind,
tmux options, hooks and format variables linked nowhere and tmux keys
read as plain code, a long member list lost which group a member
belonged to, the menus showed no release stage, and several pages still
promised a tmux their ports now refuse.

Shared source: libtmux/docs
From: 7ffc04bceec2cada8149a32e46926cba9fa9ecd2
To:   4e891632a66a144bd9dd7747168cf9218eb32710

what:
- Read a package version or release tag as stable when it is exactly
  MAJOR.MINOR.PATCH, with an optional v and package label, so a final
  release such as v0.1.0 gets a stable badge instead of throwing, and
  word the stable badge line "Stable release." without naming a
  registry; a declared stage and a stable registry status still outrank
  the name
- Julia only: build the Julia port's docs with tmux 3.7c, the version
  Julia requires, compiled by the `build-tmux` command of the Julia
  checkout's matrix tool and put on PATH only after that build succeeds
- Julia only: show the Julia core, workspace and MCP install commands
  for the documented source revision when the build selects one and for
  the default branch otherwise, and state Julia 1.13.1 and tmux 3.7c or
  newer as the floor
- Julia only: pass the Documenter `@raw html` blocks of the Julia guides
  through as page HTML with their `../source/` links rewritten to the
  documented revision on GitHub, and keep the explicit API references
  and overviews of those guides inside the selected preview version

why: Go example pages opened on a whole program with no path from the
tmux commands to the code that runs them. The API extraction of the
TypeScript, Rust, Java, Kotlin, Scala and Swift references dropped the
`#` comment lines of shell, Python, Ruby and YAML examples in doc
comments as if they were rustdoc setup lines. Swift reference signatures
printed their parameter list twice, Ruby and Swift type keywords showed
as unresolved type names, and the publisher refused the PowerShell
port's .NET alpha.22 dependency against its alpha.20 navigation pin. The
stage resolver threw on the final release tag v0.1.0 of libtmux-julia.

Shared source: libtmux/docs
From: 4e891632a66a144bd9dd7747168cf9218eb32710
To:   de7abd597bd9205c54d01498d8cdcb0bb0ec37d9

why: Sphinx consumers need discoverable port references, and the root
publisher needs a catalog for the selected default version.

what:
- Adopt scoped inventories, catalogs and footer discovery
- Adopt the reference fixes and generic links from docs PR 157
- Use the shared publisher's locked uv, Ruff and ty tooling
- Restrict scoped inventory to the actual port/version mount
- Place inventory setup help under the site meta section
- Declare the three-day uv cooldown for portable locked installs
- Make the Python CLI checks executable for Linux Ruff
- Keep decorative kind marks out of row and inventory names
- Resolve command options under native Sphinx program contexts
- Keep both docs workflow pins on the same revision

validation: YAML, callee bindings, paired pins and minimal diffs pass.
The combined docs branch passes 221 site and 23 Swift model checks,
Ruff, formatting, ty and TypeScript checks; 23 assembled-tree contracts
were skipped. Complete publication evidence remains a separate gate.

Docs source: libtmux/docs@205ecac

why: Documentation builds and their publisher must share the producer
that exports durable inventories and working footer help links.

what:
- Pin the producer and publisher to the current inventory draft.
- Adopt scoped tmux inventories, verified Sphinx examples and accessible
  setup links from libtmux/docs#166.

Producer: libtmux/docs@31ed443

why: Use the inventory producer rebased onto the current docs main.
The shared workflow also installs Julia's tested tmux runtime.

what:
- Pin the build and deploy workflows to the same revision

Producer: afb819293ce536e4df3d9ecd8e619710591f27f2

why: Keep the site builder and publisher on the reviewed producer after rebasing docs onto current main.

what:
- Pin both workflow references to the rebased docs revision.