Skip to content

docs(workspace) add native CLI guides and references - #12

Draft
tony wants to merge 22 commits into
mainfrom
workspace-cli
Draft

tony wants to merge 22 commits into
mainfrom
workspace-cli

Conversation

@tony

@tony tony commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Native workspace commands now exist on the port branches, while the site still described only builder libraries. This adds native installation and workflow guides, tmuxp syntax references, configuration examples, and explicit per-port coverage. The site identifies these CLIs as partial and unreleased, keeps builder APIs under Internals, and carries the same availability into navigation and machine-readable documentation.

.NET import, pane-order and terminal guidance, Java generated artifacts, and Swift live child output now match their native implementations. Load and shell examples share each installation guide’s socket and input. Source links and the affected visual baselines are current.

Current Rust and Swift source models and MCP registrations are refreshed from authenticated clean checkouts and actual stdio discovery. Tool links follow advertised wire names. Discovery builds native targets before capture and joins owned processes before returning.

The test runner retains isolation and its development budgets. Publication checks preserve runner failures, and assembled-product tests await Happy DOM cleanup instead of accumulating windows.

Reference navigation collapses the product menu and symbol tree together on narrow screens and restores keyboard focus when resizing closes it. Clipboard widgets preserve focus, report refused writes, and announce results through accessible status regions. Visual baselines reflect the reviewed current navigation and API models.

Validation: source suites, lint, types, and fresh browser rendering at 1440/768/390 pass within the existing development budgets. Complete assembly, link and reference audits, assembled-output tests, fonts, mobile navigation, clipboard behavior, tables, visual regression, native navigation, and gp-sphinx style parity pass. ShellCheck passes with its installed version selected explicitly. The full assembly passes 16,712 pages and 2,243,606 links with no broken targets; the two expected API-link screenshot changes are reviewed, and all remaining browser/native checks pass. Hosted checks are running for the current head. This PR remains draft while the native ports complete their broader acceptance work.

@tony
tony deployed to docs-preview September 13, 2026 00:31 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 03:13 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 09:52 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 14:36 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 15:00 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 17:04 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 17:49 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 19:19 — with GitHub Actions Active
@tony
tony deployed to docs-preview September 13, 2026 20:54 — with GitHub Actions Active
tony added 13 commits September 15, 2026 21:24
Record exact command arguments with the shell builtin so each simulated
AWS operation avoids a new Node process. Keep argument-boundary checks
and all publication assertions.
Cache isolated test transforms and parse generated model JSON directly.
Keep two test workers and every assertion, with the existing 2/10/60-second
limits. Cold and warm checks, JSON cache invalidation, and the full browser
check pass.
why: Source builds now provide workspace commands, while the site still
presented native ports only as builder libraries. Current MCP registries
also outgrew the committed source models and tool-name mappings.

what:
- Add native installation, workflow, configuration and compatibility pages
  for each port while identifying unpublished and unsupported behavior.
- Keep builder internals, language switching, sidebars and machine-readable
  documentation aligned with the new workspace pages.
- Refresh authenticated source models and live MCP discovery snapshots;
  build source targets before capture and join owned discovery processes.
- Resolve current MCP wire names and cross-port links from runtime data.

Verified source tests, lint, type checks and fresh browser rendering at
1440, 768 and 390 pixels. The outer loop passes in 43.81 seconds.

The full assembly checks 16,705 pages and 2,241,300 links with no broken
targets. Product output checks now await Happy DOM cleanup; all 17 pass
after the former no-op window.close() exhausted the worker heap.
why: The port menu pushed reference headings below the phone viewport, and resizing left the symbol tree closed on desktop.

what:
- Keep products and contents inside one native disclosure
- Follow the desktop breakpoint and remove its listener on navigation
- Verify collapsed, expanded and resized navigation in browser checks
why: Clipboard fallback reported success even when copying was denied, and removing its textarea discarded keyboard focus.

what:
- Report the copy result and restore focus after fallback cleanup
- Exercise 15 accepted and refused writes against actual widget scripts
- Run independent browser checks concurrently within the outer budget
Document C++ progress and cancellation, Go tree listings, and Java/Swift layout preflight. Refresh mention locations after the content changes. The complete outer check passes in 44.90 seconds.
why: The native C++ guides still described completion as unavailable
and omitted supported importer behavior.

what:
- Show Bash, Zsh and Fish setup and dynamic-name limitations
- Describe importer grouping, paths, aliases and explicit refusals
- Align installation limits with implemented native progress
Describe local option capture and JSON v2 saved layouts now supported by the
native CLI, including inherited environment and option limits.
why: Native workspace users need matching MCP build, endpoint and
inspection instructions.

what:
- Add seven source-pinned development workflows and overview links
- Correct current CLI coverage while retaining released MCP contracts
Describe .NET imports and attachment, Java generation artifacts, and Swift streaming and cancellation. Align load and shell examples with their installation socket and input paths. Refresh source links and the two affected visual baselines.
Retain the current API tree while reflecting the branch Swift API additions and Python workspace mentions. The full publication gate passes all 36 screenshot comparisons.
The page said Swift import "rejects ERB" without qualification. It refuses
unexpanded ERB in a Tmuxinator source, which Ruby would have expanded before
parsing, and preserves the same text in a Teamocil source, which no template
engine reads. All seven ports now draw the boundary there.

Regenerates the mentions index for the shifted line numbers.
The rebase onto the reference-tree trunk took main's index at each
conflict, which dropped the entries for the pages this branch adds.
Regenerated from the rebased tree.
The audit evidence directory is 3.1G of generated verification output that
is kept on disk and never committed. Without an ignore entry every status
check in that worktree reports it untracked, which hides real unstaged work.
Its own .gitignore only covers subfolders, so the entry has to be here.
The configuration pages described how an explicit relative start_directory
resolves but never said what happens when a document names none at all. That
is the common case, and until today three ports answered it differently from
the reference: go, java and rs started panes in the workspace file's
directory where tmuxp and the other four used the invocation directory.

All eight now agree on the invocation directory, verified against a real
tmux 3.7d on every port, so the rule is worth stating where readers look for
it rather than leaving it to be discovered.
oxlint reported withPortRoot as imported and never used in api-models.ts
and product-api.ts. Both predate this branch and neither file references
the symbol anywhere else, so the import is the whole of it.

site lint now reports nothing at all; type-check stays at zero errors and
the suite at 965 passing.
@tony
tony deployed to docs-preview September 16, 2026 02:58 — with GitHub Actions Active
The freeze pages described the reference tool but never said what the
native ports put in the document. Three of those decisions changed this
week and a user with a saved capture needs to find them: window options
move under options_after, a pane at its shell gets no shell_command, and
the document carries nothing about the machine that captured it.

The last one is the reason to write this down rather than leave it
implied. A capture used to carry the session environment and the
capturing terminal size, so reloading it elsewhere pinned the window to
80x24 and pointed SSH_AUTH_SOCK at a socket that had gone.

The Python reference page is untouched: it writes a different document.
Adding the "what the captured document holds" section to the seven native
freeze pages introduced symbol mentions the index does not know about, and
the publication suite checks that index against the prose.

I ran the vitest suite after that edit and not test-all.sh, which is where
the mention check lives, so CI found it rather than I did.
@tony
tony deployed to docs-preview September 16, 2026 03:41 — with GitHub Actions Active
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