overmux 0.0.4 → 0.0.6

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

@@ -0,0 +1,370 @@
+---
+title: Client API Reference
+---
+
+## 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,209 @@
+---
+title: Theming and CSS
+---
+
+Your Overmux UI owns its CSS. Overmux provides shared theme variables, light/dark defaults, and theme scopes for individual sections.
+
+## Load your CSS
+
+Import your stylesheet from your browser entry point:
+
+```tsx
+import { OvermuxHost } from "overmux/client";
+import { createRoot } from "react-dom/client";
+
+import definition from "./app";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <OvermuxHost definition={definition} />,
+);
+```
+
+Overmux components load their own styles automatically. Use ordinary CSS and component `className` props to customize them. Overmux defaults use CSS layers, so normal unlayered application styles take precedence.
+
+## Choose light or dark
+
+Set appearance in your client definition:
+
+```tsx
+import { defineOvermuxClient } from "overmux/client";
+
+export default defineOvermuxClient({
+  commands: {},
+  component: App,
+  appearance: {
+    scheme: "dark",
+    contrast: "auto",
+  },
+});
+```
+
+- `scheme`: `"system"` (default), `"light"`, or `"dark"`.
+- `contrast`: `"auto"` (default), `"normal"`, or `"high"`.
+
+`"system"` follows the system color preference. `"auto"` follows the system preference for increased contrast.
+
+Appearance applies to your app and Overmux-owned UI inside `OvermuxHost`. It changes built-in defaults, not custom CSS variables.
+
+## Set colors, fonts, and other theme variables
+
+Define shared variables in your stylesheet. This example supplies a custom dark palette and every shared theme variable:
+
+```css
+:root {
+  --om-color-canvas: #111318;
+  --om-color-surface: #191c24;
+  --om-color-panel: #222735;
+  --om-color-fg: #eef0f6;
+  --om-color-muted: #a3adc2;
+  --om-color-border: #394156;
+  --om-color-accent: #b59aff;
+  --om-color-accent-fg: #111318;
+  --om-color-danger: #ff8b82;
+  --om-color-success: #65d6a2;
+
+  --om-font-sans: "Inter", sans-serif;
+  --om-font-mono: "JetBrains Mono", monospace;
+
+  --om-spacing: 0.75rem;
+  --om-radius: 0.5rem;
+  --om-elevation: 0 0.75rem 2rem rgb(0 0 0 / 30%);
+  --om-focus-ring: 0 0 0 3px rgb(181 154 255 / 30%);
+  --om-motion-duration: 120ms;
+}
+```
+
+### Colors
+
+- `--om-color-canvas`: page background.
+- `--om-color-surface`: content surface background.
+- `--om-color-panel`: panel and grouped-content background.
+- `--om-color-fg`: primary text.
+- `--om-color-muted`: secondary text.
+- `--om-color-border`: borders and separators.
+- `--om-color-accent`: highlighted controls and actions.
+- `--om-color-accent-fg`: text on an accent background.
+- `--om-color-danger`: errors and destructive states.
+- `--om-color-success`: success states.
+
+### Fonts
+
+- `--om-font-sans`: interface font family.
+- `--om-font-mono`: monospace font family.
+
+Load custom fonts yourself; these variables only select them.
+
+#### Loading custom fonts
+
+Load fonts with `@font-face`, then reference their family names in your theme variables:
+
+```css
+@font-face {
+  font-family: "My Font";
+  src: url("./fonts/my-font.woff2") format("woff2");
+  font-display: swap;
+}
+
+:root {
+  --om-font-sans: "My Font", sans-serif;
+}
+```
+
+For a monospace font, use the same approach with `--om-font-mono`.
+
+### Spacing and effects
+
+- `--om-spacing`: base spacing used by components.
+- `--om-radius`: base corner radius.
+- `--om-elevation`: elevated-surface box shadow.
+- `--om-focus-ring`: additional focus box shadow.
+- `--om-motion-duration`: transition duration.
+
+Components decide which variables they use.
+
+### Applying your theme
+
+Variables on `:root` reach both your application and Overmux-owned UI, including recovery, update, and settings screens. The separate login screen does not load userland CSS.
+
+Use the same variables in your own components:
+
+```css
+body {
+  margin: 0;
+  background: var(--om-color-canvas);
+}
+
+.panel {
+  color: var(--om-color-fg);
+  background: var(--om-color-surface);
+  border: 1px solid var(--om-color-border);
+  border-radius: var(--om-radius);
+  padding: var(--om-spacing);
+}
+```
+
+Overmux does not paint your application's page background for you.
+
+Public `--om-*` variables are override inputs: Overmux does not populate them with its built-in palette. Define them before using them in your own CSS, or supply CSS fallbacks.
+
+Custom values remain in effect when `scheme` changes. If you supply a custom palette, you also own its light/dark variants and any saved theme preference.
+
+## Theme one section
+
+Wrap a section in `OvermuxThemeScope`:
+
+```tsx
+import { OvermuxThemeScope } from "overmux/client";
+
+<OvermuxThemeScope
+  scheme="light"
+  contrast="normal"
+  className="preview"
+  style={{ "--om-color-accent": "rebeccapurple" }}
+>
+  <Preview />
+</OvermuxThemeScope>;
+```
+
+The scope renders a wrapper `<div>` and applies appearance to its contents.
+
+Custom CSS variables inherit normally. A light scope inside a custom dark palette will still inherit those custom colors unless you override them.
+
+`OvermuxHost` already creates an application-wide scope. A scope inside your app affects only that section, not surrounding Overmux-owned UI.
+
+## Keep overlays themed
+
+Use `OvermuxPortal` for menus, dialogs, and other overlays:
+
+```tsx
+import { OvermuxPortal, OvermuxThemeScope } from "overmux/client";
+
+<OvermuxThemeScope scheme="dark">
+  <Editor />
+  <OvermuxPortal>
+    <EditorMenu />
+  </OvermuxPortal>
+</OvermuxThemeScope>;
+```
+
+The overlay renders inside the nearest theme scope, preserving its appearance and inherited variables.
+
+If you supply an external container, you own its theme attributes and CSS variables:
+
+```tsx
+<OvermuxPortal
+  external={{
+    container: overlayElement,
+    scopeAttributesAndVariables: "caller-owned",
+  }}
+>
+  <EditorMenu />
+</OvermuxPortal>;
+```
+
+## Packages
+
+Packages use shared `--om-*` variables where applicable. They may also expose additional CSS variables, `className`, `classNames`, or other styling props.
+
+Some rendered content has separate theme options rather than inheriting CSS colors. See each package's documentation for its styling controls.

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