overmux 0.0.4 → 0.0.5

package/dist/docs/400-reference/600-client/100-api.md

@@ -0,0 +1,370 @@
+---
+title: Client API
+---
+
+## defineOvermuxClient
+
+`defineOvermuxClient` defines your browser application: its root React component, commands, appearance, and navigation behavior. It returns the definition for `OvermuxHost` to mount; it does not render the application itself.
+
+```tsx
+// src/ui/app.tsx
+import { defineOvermuxClient } from "overmux/client";
+
+const App = () => <main>Overmux is running.</main>;
+
+export default defineOvermuxClient({
+  component: App,
+  commands: {},
+});
+```
+
+| Option | Purpose |
+| --- | --- |
+| `component` | Required root React component. |
+| `commands` | Required command registry. Use `{}` when your application has no commands, or pass a registry created with `defineCommandRegistry`. |
+| `appearance` | Optional theme preferences: `scheme` is `"dark"`, `"light"`, or `"system"` (default); `contrast` is `"auto"` (default), `"high"`, or `"normal"`. |
+| `navigate` | Optional `(route: string) => unknown` callback for validated deep links targeting the current instance. The route includes its query and fragment. Supply your router's navigation function to avoid a full page reload; by default, Overmux uses document navigation on the current origin. |
+| `shortcutOverrides` | Optional map from command IDs to replacement keyboard bindings. An empty array removes a command's default bindings. |
+| `chordPrefixes` | Optional prefixes for multi-step keyboard shortcuts. Each entry has a `binding` and `unmatched: "replay-to-focused-input"`, which replays buffered keystrokes to a focused input registered with `useShortcutInputTarget` when the sequence does not match or times out. |
+
+The function validates shortcut overrides and chord prefixes, then returns the supplied definition while preserving its command IDs for type checking.
+
+## OvermuxHost
+
+`OvermuxHost` mounts your client definition inside the Overmux browser runtime. Your application owns the browser entry point and calls React's `createRoot`; the host provides the server connection, query cache, command and shortcut handling, and theme around your root component.
+
+```tsx
+// src/ui/main.tsx
+import { OvermuxHost } from "overmux/client";
+import { createRoot } from "react-dom/client";
+
+import definition from "./app";
+import "./styles.css";
+
+const root = document.querySelector("#root");
+if (!root) {
+  throw new Error("Missing root element");
+}
+
+createRoot(root).render(<OvermuxHost definition={definition} />);
+```
+
+Here, `./app` exports the definition from the previous section. Your HTML entry point must contain an element with `id="root"` and load this module.
+
+The required `definition` prop is the object returned by `defineOvermuxClient`. Supply your root component through `definition.component`, not as children of `OvermuxHost`. Components using Overmux runtime hooks must render inside that hosted application.
+
+The host loads the server's available API definitions before rendering your component. It displays a recovery screen during startup or when startup fails, redirects to login when authentication is required, and catches rendering errors in your application. Unmounting it disposes the server connection and runtime subscriptions.
+
+## createOvermuxHooks
+
+`createOvermuxHooks` creates hooks typed from the default export of your server module. Create them once in a shared UI module, then import individual hooks from that module. The server type determines the permitted resource, operation, and stream IDs and their input, output, and message shapes.
+
+```tsx
+// src/ui/overmux.ts
+import { createOvermuxHooks } from "overmux/client";
+import type server from "../server/index";
+
+export const { useInstance, useOperation, useResource, useStream } =
+  createOvermuxHooks<typeof server>();
+```
+
+This assumes `src/server/index.ts` default-exports the `defineOvermuxServer(...)` result. The following hook examples import from `./overmux`; that is the application-owned module above. The `import type` keeps server implementation code out of the browser bundle.
+
+## useResource
+
+`useResource` reads a server resource and keeps it current when a subscription resource invalidates it. It accepts the resource's application-defined ID and exactly the input shape declared by that resource's contract.
+
+```tsx
+// src/ui/workspace-name.tsx
+import { useResource } from "./overmux";
+
+export const WorkspaceName = ({ workspaceId }: { workspaceId: string }) => {
+  const workspace = useResource({ id: "workspace", input: { workspaceId } });
+
+  if (workspace.status === "pending") return <p>Loading…</p>;
+  if (workspace.status === "error") return <p>{workspace.error.message}</p>;
+  return <h1>{workspace.data.name}</h1>;
+};
+```
+
+This application defines a `workspace` resource whose input is `{ workspaceId: string }` and output is `{ name: string }`. The result has `status: "pending" | "error" | "success"`, `refetch()`, and data or error appropriate to that status. Inputs are serialized into the query key, so use JSON-serializable values. A changed ID or input reads a separate cached resource.
+
+## useOperation
+
+`useOperation` returns a TanStack Query mutation for a server operation. Call `mutate` for fire-and-forget UI events or await `mutateAsync` when subsequent work needs its typed result.
+
+```tsx
+// src/ui/rename-workspace-button.tsx
+import { useOperation } from "./overmux";
+
+export const RenameWorkspaceButton = ({ workspaceId }: { workspaceId: string }) => {
+  const renameWorkspace = useOperation({ id: "renameWorkspace" });
+
+  return (
+    <button
+      disabled={renameWorkspace.isPending}
+      onClick={() => renameWorkspace.mutate({ name: "Planning", workspaceId })}
+    >
+      Rename workspace
+    </button>
+  );
+};
+```
+
+Here `renameWorkspace` is an application-defined operation accepting `{ workspaceId: string; name: string }`; its return type, error state, reset behavior, and mutation status come from the mutation result. Pass `signal` to the hook when the operation should observe an `AbortSignal`. Operations do not automatically refresh resources - the server handler should invalidate affected resources, or the UI can refetch them.
+
+## useStream
+
+`useStream` opens a bidirectional server stream for the component lifetime. The stream's ID, open input, outgoing message, and incoming message shapes all come from the server contract.
+
+```tsx
+// src/ui/terminal.tsx
+import { useEffect, useState } from "react";
+
+import { useStream } from "./overmux";
+
+export const Terminal = ({ paneId }: { paneId: string }) => {
+  const terminal = useStream({ id: "terminal", input: { paneId } });
+  const [output, setOutput] = useState("");
+
+  const { subscribe } = terminal;
+  useEffect(
+    () => subscribe(({ data }) => setOutput((value) => value + data)),
+    [subscribe],
+  );
+
+  return (
+    <section>
+      <pre>{output}</pre>
+      <button
+        disabled={terminal.status !== "open"}
+        onClick={() => terminal.send({ data: "ls\r", type: "input" })}
+      >
+        List files
+      </button>
+    </section>
+  );
+};
+```
+
+This application defines `terminal` with open input `{ paneId: string }`, client messages `{ type: "input"; data: string }`, and server messages `{ data: string }`. `status` is `"opening"`, `"open"`, or `"closed"`; `connectionId` changes for each server-confirmed lifetime, including reconnects. `send` returns `false` when no stream is currently available. `subscribe` returns an unsubscribe function. The hook closes its stream on unmount or when its ID/input changes; `close()` closes it earlier.
+
+## useInstance
+
+`useInstance` returns the discovered server identity, or `undefined` until it is available.
+
+```tsx
+// src/ui/open-in-overmux.tsx
+import { useInstance } from "./overmux";
+
+export const OpenInOvermux = () => {
+  const instance = useInstance();
+  return <code>{instance?.deepLinkPrefix ?? "Connecting…"}</code>;
+};
+```
+
+The identity includes `instanceId` and `deepLinkPrefix`, the prefix used to construct links to this running instance. It updates when discovery changes.
+
+## defineCommandRegistry
+
+`defineCommandRegistry` defines named commands for `defineOvermuxClient`. Each command has a title, optional default keyboard bindings, optional Zod `params`, and optionally a default `run` implementation. It returns the same registry with each object key attached as its typed command ID.
+
+```tsx
+// src/ui/commands.ts
+import { defineCommandRegistry } from "overmux/client";
+import { z } from "zod";
+import type server from "../server/index";
+
+export const commands = defineCommandRegistry<typeof server>()({
+  closePane: {
+    defaultBindings: [["§", "X"]],
+    params: z.object({ paneId: z.string() }),
+    run: ({ overmuxServerApi, params }) =>
+      overmuxServerApi.executeOperation("closePane", { paneId: params.paneId }),
+    title: "Close pane",
+  },
+  openSettings: { title: "Open settings" },
+});
+```
+
+`closePane` is an application command with a `paneId` parameter, and the server defines a `closePane` operation with matching `{ paneId: string }` input. `OvermuxServerApi` is the typed, client-safe server bridge supplied to default command handlers. It exposes `executeOperation(id, input?, signal?)`, plus `getInstanceId()` and `getDeepLinkPrefix()`; it cannot read resources or open streams. A command without `run`, such as `openSettings`, requires each registration to provide a local handler.
+
+Bindings are key-binding strings or arrays of two or more strings for a chord. A binding may also be conditional with `{ binding, when: { media } }`; its media query determines whether it is active. Invalid bindings fail when the registry is defined.
+
+## useCommand
+
+`useCommand` registers a command implementation for the mounted component. When multiple registrations exist, the one containing the focused element wins; otherwise the most recently registered one wins.
+
+```tsx
+// src/ui/pane.tsx
+import { useRef } from "react";
+
+import { useCommand } from "overmux/client";
+
+import { commands } from "./commands";
+
+export const Pane = ({ paneId }: { paneId: string }) => {
+  const element = useRef<HTMLDivElement>(null);
+  useCommand(commands.closePane, { element, params: { paneId } });
+
+  return <div ref={element}>Pane {paneId}</div>;
+};
+```
+
+The default `closePane.run` from the registry runs here with these parameters. Pass `run` to replace that implementation locally, or `enabled: false` to expose but disable it. Commands with `params` require params. Commands with no default `run` require a local `run`. Registration is removed on unmount.
+
+## useCommands
+
+`useCommands` returns the commands registered in the current hosted application, ready for a command palette or menu.
+
+```tsx
+// src/ui/command-list.tsx
+import { useCommands } from "overmux/client";
+
+export const CommandList = () => (
+  <ul>
+    {useCommands().map((command) => (
+      <li key={command.id}>
+        <button disabled={!command.enabled} onClick={() => void command.execute()}>
+          {command.title}
+        </button>
+      </li>
+    ))}
+  </ul>
+);
+```
+
+Each entry has `id`, `title`, active `bindings`, `enabled`, optional `disabledReason`, and `execute()`. Only registered commands appear. The list reflects focus-sensitive command selection and active conditional bindings.
+
+## skipToken
+
+`skipToken` conditionally removes a parameterized command registration or skips a resource read while preserving hook call order.
+
+```tsx
+// src/ui/selected-pane.tsx
+import { skipToken, useCommand } from "overmux/client";
+
+import { commands } from "./commands";
+import { useResource } from "./overmux";
+
+export const SelectedPane = ({ paneId }: { paneId?: string }) => {
+  const pane = useResource({ id: "pane", input: paneId ? { paneId } : skipToken });
+  useCommand(commands.closePane, paneId ? { params: { paneId } } : skipToken);
+
+  return pane?.status === "success" ? <p>{pane.data.title}</p> : null;
+};
+```
+
+This application defines the `pane` resource with `{ paneId: string }` input and `{ title: string }` output. A skipped resource returns `undefined` and does not fetch or subscribe. `skipToken` is valid only for commands that declare params; parameterless commands must always register.
+
+## useShortcutInputTarget
+
+`useShortcutInputTarget` identifies an input that can receive replayed keystrokes from an unmatched configured chord prefix. Register it only when `definition.chordPrefixes` includes that prefix with `unmatched: "replay-to-focused-input"`.
+
+```tsx
+// src/ui/search.tsx
+import { useRef } from "react";
+import { useShortcutInputTarget } from "overmux/client";
+
+export const Search = () => {
+  const container = useRef<HTMLDivElement>(null);
+  const input = useRef<HTMLInputElement>(null);
+  useShortcutInputTarget({ container, input });
+
+  return <div ref={container}><input ref={input} aria-label="Search" /></div>;
+};
+```
+
+When focus is inside `container`, an unmatched or timed-out prefix is replayed to `input`; the deepest matching container wins. The host waits one second for the rest of a chord. Escape cancels a pending chord without replaying it. The hook unregisters on unmount.
+
+## formatShortcutBinding
+
+`formatShortcutBinding` formats a shortcut binding for display using the current platform's key labels.
+
+```tsx
+// src/ui/shortcut-hint.tsx
+import { formatShortcutBinding } from "overmux/client";
+
+const closePaneBinding = ["§", "X"] as const;
+
+export const ShortcutHint = () => <kbd>{formatShortcutBinding(closePaneBinding)}</kbd>;
+```
+
+The binding above is a two-step chord, displayed as its formatted keys separated by spaces. Use the same binding shape accepted by command `defaultBindings` or shortcut overrides.
+
+## OvermuxThemeScope
+
+`OvermuxThemeScope` applies Overmux theme variables and creates a local overlay root for its descendants. `OvermuxHost` already provides one around the application; use another scope to isolate an embedded area or override its appearance.
+
+```tsx
+// src/ui/embedded-preview.tsx
+import { OvermuxThemeScope } from "overmux/client";
+
+export const EmbeddedPreview = () => (
+  <OvermuxThemeScope scheme="dark" contrast="high" style={{ "--om-color-accent": "#ff8a00" }}>
+    <section>Preview</section>
+  </OvermuxThemeScope>
+);
+```
+
+`scheme` defaults to `"system"` and accepts `"dark"` or `"light"`; `contrast` defaults to `"auto"` and accepts `"high"` or `"normal"`. `style` accepts normal React CSS properties plus documented `--om-*` theme tokens. Nested scopes inherit normally through CSS but own their portal roots.
+
+## OvermuxPortal
+
+`OvermuxPortal` renders children into the nearest `OvermuxThemeScope` overlay root, keeping overlays within that scope's theme and stacking context.
+
+```tsx
+// src/ui/dialog.tsx
+import { OvermuxPortal } from "overmux/client";
+
+export const Dialog = () => (
+  <OvermuxPortal>
+    <div role="dialog">Saved</div>
+  </OvermuxPortal>
+);
+```
+
+Outside a theme scope it uses `document.body`. Pass `external={{ container, scopeAttributesAndVariables: "caller-owned" }}` to render into another element. That explicit marker means the caller, not Overmux, must ensure the external container has the needed theme attributes and CSS variables.
+
+## Clipboard
+
+`readClipboardText` and `writeClipboardText` read and write plain text through the browser Clipboard API. On the Overmux desktop host, writes dispatch through its clipboard bridge; reads still use the browser API.
+
+```tsx
+// src/ui/copy-link.tsx
+import { writeClipboardText } from "overmux/client";
+
+export const CopyLink = () => (
+  <button onClick={() => void writeClipboardText(window.location.href)}>Copy link</button>
+);
+```
+
+To read text, import and await `readClipboardText`:
+
+```ts
+import { readClipboardText } from "overmux/client";
+
+export const pasteInto = async (input: HTMLTextAreaElement) => {
+  input.value = await readClipboardText();
+};
+```
+
+Both functions return promises and reject when their browser capability is unavailable or permission is denied. Desktop write resolution confirms dispatch, not completion. Call them from a user gesture where browsers require it.
+
+## Background notifications
+
+`enableBackgroundNotifications` requests permission, creates or reconciles a browser push subscription, and stores it with the server. `disableBackgroundNotifications` removes the stored subscription when possible. Configure background delivery on the server before exposing these controls.
+
+```tsx
+// src/ui/notification-settings.tsx
+import { disableBackgroundNotifications, enableBackgroundNotifications } from "overmux/client";
+
+export const NotificationSettings = () => (
+  <p>
+    <button onClick={() => void enableBackgroundNotifications()}>Enable notifications</button>
+    <button onClick={() => void disableBackgroundNotifications()}>Disable notifications</button>
+  </p>
+);
+```
+
+`enableBackgroundNotifications()` resolves `true` only after permission and subscription setup succeed; it resolves `false` for unavailable support or declined permission, and rejects for setup or server failures. It requires a secure context, service worker, Push API, and Notification API. It is unsupported in the desktop host; on iPhone and iPad it requires an installed Home Screen web app. Enabling and disabling are user actions because browsers may prompt for permission.

package/dist/docs/400-reference/600-client/200-theming.md

@@ -0,0 +1,94 @@
+---
+title: Theming and CSS
+---
+
+Your app owns its UI and CSS. Overmux provides scoped component styles and optional CSS variables for customization.
+
+## Appearance
+
+Set `appearance` in `defineOvermuxClient({ appearance, commands, component })`. Types are exported from `overmux/client`.
+
+| Property | Values | Default | Behavior |
+| --- | --- | --- | --- |
+| `scheme` | `"light"`, `"dark"`, `"system"` | `"system"` | Selects the fallback palette and CSS `color-scheme`. System follows `prefers-color-scheme`. |
+| `contrast` | `"normal"`, `"high"`, `"auto"` | `"auto"` | High selects system-color fallbacks; auto responds to `prefers-contrast: more`. |
+
+Browser forced colors apply regardless of `contrast`, with `forced-color-adjust: auto`. Explicit color tokens override palette fallbacks; test custom colors in each mode. Appearance does not persist preferences or configure third-party themes.
+
+## Tokens
+
+Set public tokens on `:root` for the whole document, or on a theme scope for one subtree. `OvermuxStyle` provides typed inline styles for these tokens alongside React CSS properties.
+
+| Token | CSS value | Purpose |
+| --- | --- | --- |
+| `--om-color-canvas` | Color | Page background |
+| `--om-color-surface` | Color | Main surface |
+| `--om-color-panel` | Color | Secondary background |
+| `--om-color-fg` | Color | Primary text |
+| `--om-color-muted` | Color | Secondary text |
+| `--om-color-border` | Color | Borders and separators |
+| `--om-color-accent` | Color | Interactive accents |
+| `--om-color-accent-fg` | Color | Foreground on accent backgrounds, where consumed |
+| `--om-color-danger` | Color | Errors and destructive states |
+| `--om-color-success` | Color | Success and added-content states |
+| `--om-font-sans` | Font-family list | Interface text |
+| `--om-font-mono` | Font-family list | Code and diagnostics |
+| `--om-spacing` | Length | Spacing unit; components may scale it |
+| `--om-radius` | Length | Corner radius; components may scale it |
+| `--om-elevation` | Box-shadow | Panel and popover shadows |
+| `--om-focus-ring` | Box-shadow | Focus-ring shadows |
+| `--om-motion-duration` | Time | Transition duration |
+
+Tokens apply only where components consume them. Fallbacks vary by component; runtime palette variables beginning with `--_om-` are private. **Public tokens are not populated with default palette values:** app CSS using `var(--om-color-canvas)` must define it or provide a fallback. Explicit tokens inherit normally and do not change automatically with the scheme.
+
+## `OvermuxThemeScope`
+
+Import from `overmux/client`. The host already supplies an outer scope; add scopes for local themes or portal placement.
+
+```tsx
+<OvermuxThemeScope scheme="light" style={{ "--om-color-accent": "purple" }}>
+  <Preview />
+</OvermuxThemeScope>
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `children` | `ReactNode` | Required |
+| `scheme` | `OvermuxScheme` | `"system"` |
+| `contrast` | `OvermuxContrast` | `"auto"` |
+| `className` | `string` | Unset |
+| `style` | `OvermuxStyle` | Unset |
+
+Renders a `div` with `data-om-scope`, `data-om-scheme`, `data-om-contrast`, and an internal overlay container. Sets foreground, font family, and `color-scheme`, but does not paint a background.
+
+Nested scopes resolve their own defaults, not their parent's appearance props. Public token overrides still inherit and take precedence over the nested palette. Tokens placed inside the app cannot affect ancestor host UI.
+
+## `OvermuxPortal`
+
+Import from `overmux/client`. Use `<OvermuxPortal><Popup /></OvermuxPortal>` to render overlays within the nearest theme scope.
+
+| Context | Destination |
+| --- | --- |
+| Inside a scope | Nearest scope's internal overlay container |
+| Outside a scope, in a browser | `document.body` |
+| Scope container not mounted, or no document | Nothing rendered |
+| `external={{ container, scopeAttributesAndVariables: "caller-owned" }}` | Supplied element; caller owns its scope attributes and variables |
+
+The overlay container is a sibling of the scope's children. Put shared overlay tokens on the scope, not a descendant around the portal call site. External containers receive no automatic copying of scope attributes or variables. Portals supply placement, not positioning, focus trapping, or dismissal.
+
+## CSS and integrations
+
+Import app CSS from browser code with `import "./styles.css"`. Theme scopes, the UI package, and Git, Pi, xterm, and Zellij React components import their own styles. Layout, resets, and font loading remain app-owned.
+
+Built-in styles use `@scope` and the `om.components` cascade layer, with top-level ordering `theme, base, om`. Normal unlayered app CSS takes precedence over layered styles. Theme rules stop at nested scopes, but global app selectors and inherited properties can still affect components. Browser support for `@scope` and cascade layers is required.
+
+| Component family | Shared styling | Separate configuration |
+| --- | --- | --- |
+| Runtime host UI | Theme tokens where consumed | Client `appearance` |
+| UI split views | Border and accent tokens | App owns pane contents |
+| Git React UI | Colors, fonts, spacing, radius | Diff options and themes; `registerGitDiffTheme` registers custom themes |
+| Pi React UI | Colors, fonts, spacing, radius, elevation | Code highlighting uses Tokyo Night |
+| xterm | Wrapper background: `--om-xterm-terminal-background` | `options.theme` for terminal colors; options such as `fontFamily` for fonts |
+| tmux / Zellij terminal wrappers | xterm wrapper styles | Forwarded xterm props |
+
+Scope appearance does not automatically update terminal palettes or syntax-highlighting themes.

package/dist/docs/400-reference/600-client/300-tech-stack-recommendations.md

@@ -0,0 +1,12 @@
+---
+title: Tech stack recommendations
+---
+
+We recommend:
+
+- [pnpm](https://pnpm.io/) for package management.
+- [TanStack Router](https://tanstack.com/router) for routing.
+- [shadcn/ui](https://ui.shadcn.com/) for UI components.
+- [Zod](https://zod.dev/) for schemas and runtime validation.
+
+If your app already uses a different stack, follow its existing conventions.

package/dist/docs/400-reference/{400-cli → 700-cli}/050-init.md

@@ -1,16 +1,14 @@
 ---
-title: "overmux init"
+title: "`overmux init`"
 ---
 
-# `overmux init`
-
 Create a minimal, runnable Overmux application without prompting.
 
 ```sh
 overmux init
 ```
 
-The application is created in `$XDG_CONFIG_HOME/overmux`.
+The application is created in `$XDG_CONFIG_HOME/overmux` (default `~/.config/overmux`). See [storage locations](../300-storage-locations.md) for directory defaults and overrides.
 
 The command validates the toolchain before writing files. When Mise is installed, it must be [activated in the shell](https://mise.jdx.dev/getting-started.html#activate-mise); the generated `mise.toml` pins Node 22, pnpm 10, and the latest published Overmux version. Without Mise, pnpm 10 or newer must already be available and `mise.toml` is omitted.
 

package/{docs/400-reference/400-cli → dist/docs/400-reference/700-cli}/100-serve.md

@@ -1,10 +1,7 @@
 ---
-title: "overmux serve"
-description: "Serve the Overmux web UI"
+title: "`overmux serve`"
 ---
 
-# `overmux serve`
-
 Serve the authenticated Overmux web UI. Development starts private Vite behind the public Overmux gateway. Production builds with Vite and serves static assets without running Vite.
 
 ## Usage
@@ -14,6 +11,8 @@ overmux serve [--config path] [--host host] [--port port] [--login | --no-login]
 overmux serve --production [--no-build] [--config path] [--host host] [--port port] [--login | --no-login]
 ```
 
+See [storage locations](../300-storage-locations.md) for default configuration paths, logs, and persistent data.
+
 ## Options
 
 | Flag | Description | Default |
@@ -31,3 +30,9 @@ overmux serve --production [--no-build] [--config path] [--host host] [--port po
 A grant prints one server-issued URL for every authenticated browser origin. Redeeming its code or any URL consumes the grant and authenticates only that origin; create another grant for another origin. The output identifies the browser login page, expiry, and command for creating another grant.
 
 `--no-build` without `--production` is invalid. Vite's build output cleanup follows its `build.emptyOutDir` setting.
+
+## Local instance discovery
+
+The server stores its private control socket and registration in `$XDG_RUNTIME_DIR/overmux` when `XDG_RUNTIME_DIR` is absolute. If it is unset, empty, or relative, the directory is `/tmp/overmux-<uid>`, where `<uid>` is your numeric Unix user ID. If the preferred runtime directory exceeds 80 UTF-8 bytes, Overmux instead uses `/tmp/overmux-<uid>-<hash>`, with the first 12 hexadecimal SHA-256 characters of the preferred directory path. These fallbacks use literal `/tmp`, independently of `TMPDIR` and XDG state storage.
+
+The directory must belong to the current user, must not itself be a symlink, and is secured with owner-only permissions (`0700`). The CLI uses the same location for discovery. After upgrading from a version that used state storage or another temporary directory, restart existing servers so the CLI can discover them; old locations are not searched.

package/{docs/400-reference/400-cli → dist/docs/400-reference/700-cli}/200-auth.md

@@ -1,10 +1,7 @@
 ---
-title: "overmux auth"
-description: "Manage CLI-issued browser authentication"
+title: "`overmux auth`"
 ---
 
-# `overmux auth`
-
 Manage browser login grants and sessions for a running local Overmux server.
 
 Authentication administration uses the private same-user control socket. When multiple local servers are running, use `--port` to select one.

package/dist/docs/400-reference/{400-cli → 700-cli}/300-call.md

@@ -1,10 +1,7 @@
 ---
-title: "overmux call"
-description: "Invoke an operation on a running Overmux server"
+title: "`overmux call`"
 ---
 
-# `overmux call`
-
 Invoke an operation on a running local Overmux server.
 
 The CLI discovers the local instance and obtains a short-lived bearer credential through its private same-user control socket. Use `--port` to select an instance when multiple local servers are running.

package/dist/docs/400-reference/{400-cli → 700-cli}/350-instance.md

@@ -1,10 +1,7 @@
 ---
-title: "overmux instance"
-description: "Read the identity of a running Overmux server"
+title: "`overmux instance`"
 ---
 
-# `overmux instance`
-
 Print the live server's `instanceId` and `deepLinkPrefix`. Like `overmux call`, this discovers a local running server through its private same-user control channel. It queries the identity resolved by that running server, never reloads local configuration, and does not verify HTTP or WebSocket reachability.
 
 ```sh