@greppleai/grip 0.0.0-stage → 0.0.1

package/docs/hooks.md

@@ -0,0 +1,85 @@
+# Hooks
+
+Grip supports host-local automation with a Phase 0 Claude Code-compatible hook schema. Hooks are separate from Grip extensions. Native Grip settings are preferred; Claude settings remain supported for compatibility.
+
+## Configuration and precedence
+
+For every new session, `GripAgent` captures an immutable active hook snapshot. `/reload` rereads the same trusted file-backed sources and replaces that snapshot after resolution succeeds. Trusted user sources are discovered in this order:
+
+1. `<agentDir>/settings.json` (native Grip settings; normally `~/.grip/agent/settings.json`)
+2. `~/.claude/settings.json` (Claude compatibility)
+
+Project sources are disabled by default. When the interactive CLI starts in a local repository containing project hooks, it asks whether to **Don't trust**, **Trust once**, or **Trust always**. Trust once applies to the current session, including `/reload`. Trust always stores the canonical repository location in `<agentDir>/trusted-project-hooks.json` (normally `~/.grip/agent/trusted-project-hooks.json`) and trusts all future hook changes at that location without prompting again. `--trust-project-hooks` bypasses the prompt. Embedding hosts must explicitly set `trustProjectHooks: true`. Trusted project sources are appended in this order:
+
+1. `<cwd>/.grip/settings.json` (native Grip settings)
+2. `<cwd>/.claude/settings.json` (Claude compatibility)
+3. `<cwd>/.claude/settings.local.json` (Claude compatibility local override)
+
+Handlers are additive in source order. Exact duplicate event/matcher/handler combinations execute once, with the earlier native Grip source preferred over its Claude compatibility counterpart. `disableAllHooks` retains final-included-source precedence. Initial project discovery requires local built-in operations or a custom backend identity explicitly reporting `local`; unknown and remote startup backends fail closed. After an approved local snapshot is loaded, project/local command hooks follow the active workspace backend: host-local while local, and container/remote-local after a Docker daemon or sandbox transition. Host-injected snapshots are trusted host configuration and do not use discovery.
+
+SDK hosts can use `CreateGripAgentOptions.hooks` to disable discovery, override the home directory used for Claude compatibility, inject a snapshot, or impose HTTP URL/environment ceilings. Native user hooks follow the active Grip `agentDir`. Injected snapshots are cloned and recursively frozen; `/reload` retains the injected snapshot rather than reading settings files. `loadHooks()` likewise defaults to user-only discovery; callers must explicitly select project/local sources. The complete parsing/execution types and helpers are exported from `@greppleai/grip/hooks`; only stable host options are exported at the package root.
+Example:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write",
+        "hooks": [{ "type": "command", "command": "./check-tool.sh", "timeout": 10 }]
+      }
+    ]
+  }
+}
+```
+
+## Supported events
+
+| Event | Timing and behavior |
+|---|---|
+| `SessionStart` | Lazily, once, immediately before the session's first submitted prompt in interactive, print, JSON, RPC, and SDK modes. |
+| `UserPromptSubmit` | On raw submitted text, before extension commands/input handlers, skill/rule/template expansion, prompt persistence, or provider submission. Blocking rejects the submission without persisting the prompt; the completed hook execution is still recorded in the audit trail. Context output is inserted once as hidden model-visible custom context. |
+| `PreToolUse` | After Grip's initial argument validation and before extension `tool_call`. Deny/block prevents execution. `ask` and `defer` also fail closed with distinct diagnostics because Grip has no permission engine. For Read/Edit/Write, Grip's `path` is exposed as Claude `file_path`, lexically resolved to an absolute path with the active backend's path flavor. Local POSIX `~` paths use the host home; remote or otherwise unknown homes fail closed. `updatedInput` fully replaces the arguments; `file_path` is safely mapped back to Grip `path` under the same home rule and revalidated against the active tool schema. Invalid or unsupported replacement fails closed. Deny-time additional context is included once in the blocked tool result feedback. |
+| `PostToolUse` | After successful execution. Post ordering is: built-in LSP synchronization, extension `tool_result`, then this hook. It therefore observes the extension-adjusted result. |
+| `PostToolUseFailure` | At the same post position when execution has failed. It cannot turn a failure into a successful execution. |
+| `Stop` | After retry and auto-compaction decisions, before session settlement. Receives the final assistant text directly. Blocking or additional context inserts hidden, model-visible custom hook feedback and continues the loop. Continued calls set `stop_hook_active`. Grip normally allows at most eight consecutive hook continuations; a hook can continue beyond that while reporting decreasing `continuationProgress` as described below. |
+| `StopFailure` | Emitted for a final assistant failure after retry/compaction decisions. Its output cannot continue the loop. |
+| `PreCompact` / `PostCompact` | Around successful manual and automatic compaction. Trigger is `manual` or `auto`; `PostCompact` receives the saved summary. A blocking `PreCompact` cancels compaction. |
+| `SessionEnd` | Once during `GripAgent` session replacement or disposal, before extension shutdown and session disposal. Default shared budget is 1.5 seconds; an explicit handler timeout may raise it, capped at 60 seconds. |
+
+Common input fields include a stable Grip session ID, the host repository cwd, a UUID `prompt_id` for the submitted prompt and its work, and a local file-backed session reference as `transcript_path` when available (otherwise an empty string). Hooks receive no remote transcript fetch. Built-in names are normalized to Claude names (`Read`, `Bash`, `Edit`, `Write`, `WebSearch`, `Grep`, and `Glob`); custom tool names are unchanged. File-tool inputs still use the active workspace backend's lexical paths.
+
+Matchers support match-all, exact comma/pipe alternatives, and JavaScript regular expressions. `UserPromptSubmit` and `Stop` ignore matchers, matching Claude behavior. Tool `if` conditions support the common tool/argument glob form.
+
+## Handlers and output
+
+Phase 0 executes synchronous `command` and `http` handlers. Matching handlers run concurrently; their results are aggregated deterministically in settings-source/order order. Command handlers receive JSON on stdin. HTTP handlers receive a JSON POST, reject redirects, and stream response bodies into the configured bound. Only structured JSON from successful HTTP responses is actionable; 2xx plain text is diagnosed and ignored. Plain text from successful command `SessionStart` and `UserPromptSubmit` handlers becomes context. Object-looking malformed stdout is diagnosed and discarded. Structured JSON supports common controls, but `hookSpecificOutput` fields apply only when `hookEventName` matches the active event. `systemMessage` is aggregated for every supported event and emitted only as host-facing diagnostic output; it is never added to model context. Supported model-context controls include:
+- `additionalContext`
+- `permissionDecision`, `permissionDecisionReason`, and `updatedInput` for `PreToolUse`
+- `updatedToolOutput` for `PostToolUse` (built-in tools conservatively accept strings only; custom tools may use valid `{ content, details? }` shapes)
+- `updatedMCPToolOutput` only for `mcp__` tools
+
+`continue:false` is aggregate termination, not an event block. In particular, Stop settles without a continuation. Stop continuation is requested only by `decision:"block"`, exit status 2, or Stop `additionalContext`. Pre-tool context is attached once to its corresponding result; post-tool context and block reasons are returned as model feedback.
+
+A Stop handler may set `hookSpecificOutput.continuationProgress` to a finite nonnegative number representing remaining work, where lower is better. Grip sums progress reported by matching Stop handlers. The ordinary eight-continuation limit remains when progress is absent or stalled. Beyond eight continuations, Grip keeps running while the aggregate metric establishes a new low, tolerating up to three consecutive equal or higher reports so short regressions do not terminate a converging loop. A fourth report without a new low settles the session. Progress state is local to the current prompt continuation chain and resets when the chain settles, fails, aborts, or a new prompt starts.
+Exit status 2 blocks only events with compatible preflight semantics. Timeouts, process failures, malformed output, and HTTP failures are nonfatal/fail-open unless a valid blocking result was returned. Stdout/stderr are bounded to 1 MiB each by default, while every individual model-visible context/reason field is independently capped at 10,000 characters. The session owns cancellation for all hooks; replacement/disposal cancels outstanding work, and active tool hooks also compose with the agent signal. User-aborted assistant runs do not emit Stop or StopFailure.
+
+## Interactive visibility
+
+The interactive TUI adds distinctly colored cards for hook events that execute at least one matching handler. Cards start collapsed, showing the event, subject/tool-name counts, aggregate completed/failed/cancelled call counts, and the configured expansion shortcut. Command labels, source paths, detailed statuses/timings, and returned prompt bodies are hidden until expanded. Press **Ctrl+O** (the configurable `app.tools.expand` action) to expand or collapse hook details together with ordinary tool output. New cards and cards reconstructed by `/reload` or transcript navigation inherit the current expansion state.
+
+Within one agent turn, tool-hook activity is grouped into separate `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` cards; non-tool lifecycle events remain standalone. When expanded, each unique handler is shown on its own line, while repeated handlers with the same type, displayed target, and exact source are aggregated with invocation/status counts and an approximate average execution time to one decimal place. Cards deduplicate explicit returned model-visible prompts while preserving occurrence counts. Non-actionable raw stdout and stderr are not rendered; successful plain command output accepted as model context is shown as a returned prompt. Collapsing is a presentation choice, not redaction: hook execution, model-visible context, and stored audit data are unchanged.
+
+Hook cards are persisted in JSONL as displayable, context-excluded audit messages. This preserves their original transcript positions across `/reload`, resume, and process restarts without adding them to model context. The interactive TUI renders at most the latest 200 hook cards from the active context; older audit entries remain in session storage. Print, JSON, and RPC modes do not render hook cards.
+
+Use `/hooks disable` to skip subsequent hook events for the current interactive session and `/hooks enable` to resume dispatch. Disabling hooks does not cancel a handler already executing, skipped events are not replayed, and each newly created or resumed session starts enabled. `/reload` preserves the current enabled/disabled state, refreshes hook diagnostics, and does not synthesize hook `SessionEnd` or `SessionStart` events. If hook resolution throws, the previous active snapshot remains in use. The command is user-only and excluded from model-visible slash-command catalogs.
+
+Not implemented in Phase 0: `prompt`, `agent`, and `mcp_tool` handlers; asynchronous/background handlers; prompt/agent/MCP lifecycle events; and permission events. Unsupported handlers are diagnosed and never executed.
+
+## Security and locality
+
+Hooks are trusted code. Interactive project settings are not discovered until the user approves them; the host-only SDK grant and `--trust-project-hooks` are explicit alternatives. Initial remote backends do not discover project settings. Review both `.grip` and compatibility `.claude` hook configuration before granting trust. **Trust always is location-based and includes arbitrary future hook changes at that repository path.**
+
+Project/local command hooks execute through the active workspace backend. Locally they run as the host user; after a sandbox or remote transition they execute inside that backend with its cwd and sanitized backend environment. They never fall back to host execution when a non-local backend is unavailable. Project/local HTTP hooks are rejected on non-local backends because proxying them through host networking would escape isolation. User hooks and host-injected snapshots remain host-owned even when tools are remote. File-tool input paths are lexically normalized using the active backend's POSIX/Windows semantics without probing the remote filesystem.
+
+Hook environments remove OpenTelemetry variables and Grip credential-like variables. This is defense in depth, not a general secret sandbox: locally executing hooks retain the authority of the Grip host user, while sandbox/remote project hooks retain the authority granted by that backend. Host HTTP destinations honor merged `allowedHttpHookUrls` settings policy and any host URL ceiling, require HTTPS except for literal loopback destinations, and reject redirects. HTTP header interpolation is restricted by the handler `allowedEnvVars`, merged `httpHookAllowedEnvVars` policy, and any host environment ceiling. Host and backend command execution applies bounded output, cancellation, timeout, and process-tree cleanup.

package/docs/index.md

@@ -0,0 +1,81 @@
+# Grip Documentation
+
+Grip is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, rules, prompt templates, themes, and Grip packages.
+
+## Quick start
+
+When the package is available in your registry, install Grip with npm:
+
+```bash
+npm install -g --ignore-scripts @greppleai/grip
+```
+
+`--ignore-scripts` disables dependency lifecycle scripts during install. Grip does not require install scripts for normal npm installs. This repository rename does not verify publication or ownership of the new npm scope.
+
+The former installer at `https://pi.dev/install.sh` belongs to the old Pi distribution; it is not a verified Grip installation method. Do not replace the hostname with a guessed endpoint.
+
+To uninstall Grip itself after an npm install, use:
+
+```bash
+npm uninstall -g @greppleai/grip
+```
+
+For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @greppleai/grip`, `yarn global remove @greppleai/grip`, or `bun uninstall -g @greppleai/grip`.
+
+Then run it in a project directory:
+
+```bash
+grip
+```
+
+Authenticate with `/login` for subscription providers, or set an API key such as `ANTHROPIC_API_KEY` before starting Grip.
+
+For the full first-run flow, see [Quickstart](quickstart.md). Upgrading from the previous project identity? Read [Migrating to Grip](migrating-to-grip.md); existing configuration and sessions are not moved automatically.
+
+## Start here
+
+- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
+- [Migrating to Grip](migrating-to-grip.md) - manual migration from the old CLI, packages, and configuration paths.
+- [Using Grip](usage.md) - interactive mode, slash commands, context files, and CLI reference.
+- [Providers](providers.md) - subscription and API-key setup for built-in providers.
+- [Settings](settings.md) - global and project settings.
+- [Language Server Protocol](lsp.md) - configure spawned servers, attached endpoints, host connections, and remote-backend path mappings.
+- [Remote Daemon](daemon.md) - run `grip --daemon` as a confined remote workspace runtime.
+- [Docker Sandbox](sandbox.md) - hidden user-only `/sandbox` command for Docker-backed workspace execution.
+- [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
+- [Sessions](sessions.md) - session management, branching, and tree navigation.
+- [Compaction](compaction.md) - context compaction and branch summarization.
+
+## Customization
+
+- [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
+- [Skills](skills.md) - Agent Skills for reusable on-demand capabilities.
+- [Rules](rules.md) - on-demand mandatory constraints and policies.
+- [Prompt templates](prompt-templates.md) - reusable prompts that expand from slash commands.
+- [Themes](themes.md) - built-in and custom terminal themes.
+- [Grip packages](packages.md) - bundle and share extensions, skills, rules, prompts, and themes.
+- [Custom models](models.md) - add model entries for supported provider APIs.
+- [Custom providers](custom-provider.md) - implement custom APIs and OAuth flows.
+
+## Programmatic usage
+
+- [SDK](sdk.md) - embed Grip in Node.js applications.
+- [RPC mode](rpc.md) - integrate over stdin/stdout JSONL.
+- [JSON event stream mode](json.md) - print mode with structured events.
+- [TUI components](tui.md) - build custom terminal UI for extensions.
+
+## Reference
+
+- [Session format](session-format.md) - JSONL session file format, entry types, and session APIs.
+
+## Platform setup
+
+- [Windows](windows.md)
+- [Termux on Android](termux.md)
+- [tmux](tmux.md)
+- [Terminal setup](terminal-setup.md)
+- [Shell aliases](shell-aliases.md)
+
+## Development
+
+- [Development](development.md) - local setup, project structure, and debugging.

package/docs/json.md

@@ -0,0 +1,89 @@
+# JSON Event Stream Mode
+
+```bash
+grip --mode json "Your prompt"
+```
+
+Outputs all session events as JSON lines to stdout. Useful for integrating Grip into other tools or custom UIs.
+
+## Event Types
+
+Wire events use [`JsonAgentSessionEvent`](../src/modes/json-event.ts). It matches
+[`AgentSessionEvent`](../src/core/agent-session.ts) except that streaming message updates omit cumulative snapshots:
+
+```typescript
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
+
+type JsonAgentSessionEvent =
+	| Exclude<AgentSessionEvent, { type: "message_update" }>
+	| {
+			type: "message_update";
+			assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
+		};
+```
+
+`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
+
+Other base events come from [`AgentEvent`](../../agent/src/types.ts):
+
+```typescript
+type AgentEvent =
+  // Agent lifecycle
+  | { type: "agent_start" }
+  | { type: "agent_end"; messages: AgentMessage[] }
+  // Turn lifecycle
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+  // Message lifecycle
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
+  | { type: "message_end"; message: AgentMessage }
+  // Tool execution
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+```
+
+## Message Types
+
+Base messages from [`packages/ai/src/types.ts`](../../ai/src/types.ts):
+- `UserMessage`
+- `AssistantMessage`
+- `ToolResultMessage`
+
+Extended messages re-exported by [`core/messages.ts`](../src/core/messages.ts) from `@greppleai/grip-agent-core`:
+- `BashExecutionMessage`
+- `CustomMessage`
+- `BranchSummaryMessage`
+- `CompactionSummaryMessage`
+- `CompactionSummaryMessage` (line 62)
+
+## Output Format
+
+Each line is a JSON object. Writes are serialized through the stdout queue, and provider event delivery waits for queued JSON output to drain. The first line is the session header:
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+Followed by events as they occur:
+
+```json
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],...}}
+{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_end","message":{...}}
+{"type":"turn_end","message":{...},"toolResults":[]}
+{"type":"agent_end","messages":[...]}
+```
+`message_update` records are delta-only. They omit both the cumulative `message` field and
+`assistantMessageEvent.partial` to keep stream size linear. Use `contentIndex` and `delta`
+to assemble live text, thinking, or tool-call arguments if needed. `message_end` contains
+the final authoritative message.
+
+## Example
+
+```bash
+grip --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```

package/docs/keybindings.md

@@ -0,0 +1,230 @@
+# Keybindings
+
+All keyboard shortcuts can be customized via `~/.grip/agent/keybindings.json`. Each action can be bound to one or more keys.
+
+The config file uses the same namespaced keybinding ids that Grip uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
+
+Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
+
+After editing `keybindings.json`, run `/reload` in Grip to apply the changes without restarting the session.
+
+## Key Format
+
+`modifier+key` where modifiers are `ctrl`, `shift`, `alt`, `super` (combinable) and keys are:
+
+- **Letters:** `a-z`
+- **Digits:** `0-9`
+- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
+- **Function:** `f1`-`f12`
+- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
+
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `super+k`, `ctrl+super+k`, `ctrl+1`, etc.
+
+`super` bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
+
+## All Actions
+
+### TUI Editor Cursor Movement
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.cursorUp` | `up` | Move cursor up; browse older history when empty or already browsing at the top |
+| `tui.editor.cursorDown` | `down` | Move cursor down; browse newer history at the bottom while browsing |
+| `tui.editor.historyPrevious` | *(none)* | Select the previous prompt history entry |
+| `tui.editor.historyNext` | *(none)* | Select the next prompt history entry |
+| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
+| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
+| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
+| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+home`, `ctrl+a` | Move to line start |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+end`, `ctrl+e` | Move to line end |
+| `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
+| `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
+| `tui.editor.pageUp` | `pageUp`, `ctrl+pageUp` | Scroll up by page |
+| `tui.editor.pageDown` | `pageDown`, `ctrl+pageDown` | Scroll down by page |
+
+The dedicated history actions always change history entries, regardless of the cursor position in a multiline prompt. Explicit history bindings take precedence over application actions while the main editor is focused, so binding `tui.editor.historyPrevious` to `ctrl+p` overrides model cycling in that context without changing `Ctrl+P` in selectors.
+
+### TUI Editor Deletion
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
+| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
+| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
+| `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
+| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
+| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
+
+### TUI Input
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.newLine` | `shift+enter` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab / autocomplete |
+
+### TUI Kill Ring
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
+| `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
+| `tui.editor.undo` | `ctrl+-` | Undo last edit |
+
+### TUI Clipboard and Selection
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.copy` | `ctrl+c` | Copy selection |
+| `tui.select.up` | `up` | Move selection up |
+| `tui.select.down` | `down` | Move selection down |
+| `tui.select.pageUp` | `pageUp` | Page up in list |
+| `tui.select.pageDown` | `pageDown` | Page down in list |
+| `tui.select.confirm` | `enter` | Confirm selection |
+| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
+
+### TUI Fullscreen Viewport
+
+These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content.
+
+Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
+
+| Key | Default mode | Fullscreen mode |
+|-----|--------------|-----------------|
+| `home`, `end` | Editor | Transcript |
+| `ctrl+home`, `ctrl+end` | Editor | Editor |
+| `pageUp`, `pageDown` | Editor | Transcript |
+| `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
+
+This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for smaller transcript steps while keeping the full-page bindings. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.altScreen.pageUp` | `pageUp` | Scroll the transcript up by one page |
+| `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
+| `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
+| `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
+| `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
+| `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
+| `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
+| `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
+
+### Application
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.interrupt` | `escape` | Cancel / abort |
+| `app.clear` | `ctrl+c` | Clear editor (first) / exit (second) |
+| `app.exit` | `ctrl+d` | Exit (when editor empty) |
+| `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
+| `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
+| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image or text from clipboard |
+
+### Sessions
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.session.new` | *(none)* | Start a new session (`/new`) |
+| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
+| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
+| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
+| `app.session.togglePath` | `ctrl+p` | Toggle path display |
+| `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
+| `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
+| `app.session.rename` | `ctrl+r` | Rename session |
+| `app.session.delete` | `ctrl+d` | Delete session |
+| `app.session.deleteNoninvasive` | `ctrl+backspace` | Delete session when query is empty |
+
+### Models and Thinking
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.model.select` | `ctrl+l` | Open model selector |
+| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
+| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
+| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
+
+### Display and Message Queue
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output and hook details |
+| `app.message.copy` | `ctrl+x` | Copy the last assistant message, or the selected entry in `/tree` |
+| `app.message.followUp` | `alt+enter` | Queue follow-up message |
+| `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
+
+### Tree Navigation
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
+| `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
+| `app.tree.editLabel` | `shift+l` | Edit the label on the selected tree node |
+| `app.tree.toggleLabelTimestamp` | `shift+t` | Toggle label timestamps in the tree |
+| `app.tree.filter.default` | `ctrl+d` | Set tree filter to default view |
+| `app.tree.filter.noTools` | `ctrl+t` | Toggle tree filter that hides tool results |
+| `app.tree.filter.userOnly` | `ctrl+u` | Toggle tree filter that shows only user messages |
+| `app.tree.filter.labeledOnly` | `ctrl+l` | Toggle tree filter that shows only labeled entries |
+| `app.tree.filter.all` | `ctrl+a` | Toggle tree filter that shows all entries |
+| `app.tree.filter.cycleForward` | `ctrl+o` | Cycle tree filter forward |
+| `app.tree.filter.cycleBackward` | `shift+ctrl+o` | Cycle tree filter backward |
+
+### Scoped Models Selector
+
+Used inside the scoped models selector (opened via `/scoped-models`).
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.models.save` | `ctrl+s` | Save current model selection to settings |
+| `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
+| `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
+| `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
+| `app.models.reorderUp` | `alt+up` | Move the selected model up in the cycle order |
+| `app.models.reorderDown` | `alt+down` | Move the selected model down in the cycle order |
+
+## Custom Configuration
+
+Create `~/.grip/agent/keybindings.json`:
+
+```json
+{
+  "tui.editor.historyPrevious": "ctrl+p",
+  "tui.editor.historyNext": "ctrl+n",
+  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
+}
+```
+
+Each action can have a single key or an array of keys. User config overrides defaults.
+
+On native Windows, `app.suspend` has no default binding because Windows terminals do not support Unix job control. If you bind it manually, Grip shows a status message instead of suspending. In WSL, the normal Linux `ctrl+z`/`fg` behavior still applies.
+
+### Emacs Example
+
+```json
+{
+  "tui.editor.historyPrevious": "ctrl+p",
+  "tui.editor.historyNext": "ctrl+n",
+  "tui.editor.cursorLeft": ["left", "ctrl+b"],
+  "tui.editor.cursorRight": ["right", "ctrl+f"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
+  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
+  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
+  "tui.input.newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
+### Vim Example
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "alt+k"],
+  "tui.editor.cursorDown": ["down", "alt+j"],
+  "tui.editor.cursorLeft": ["left", "alt+h"],
+  "tui.editor.cursorRight": ["right", "alt+l"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
+}
+```