docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,124 @@
+# Ghostty Terminal — Overview
+
+[Ghostty](https://ghostty.org) is a cross-platform, GPU-accelerated terminal emulator with an INI-style configuration system, Shadertoy-compatible custom shaders, and a rich CLI for introspection.
+
+See [Configuration Reference](configuration.md) for the complete option catalog.
+
+---
+
+## CLI Actions
+
+| Command | Description |
+|---------|-------------|
+| `+version` / `--version` | Display Ghostty version |
+| `+list-fonts` | List all available fonts |
+| `+list-keybinds` | List all current/default keybinds |
+| `+list-themes` | List all available themes |
+| `+list-colors` | List all named RGB colors |
+| `+list-actions` | List all available keybind actions |
+| `+ssh-cache` | Manage SSH terminfo cache |
+| `+edit-config` | Open config file in $EDITOR/$VISUAL |
+| `+show-config` | Show current configuration |
+| `+show-config --default --docs` | Show all options with docs |
+| `+validate-config` | Validate a config file |
+| `+crash-report` | List existing crash reports |
+| `+new-window` | Open new window in running instance |
+
+### Useful Flag Combinations
+
+```bash
+# Show all config options with their docs as comments
+ghostty +show-config --default --docs
+
+# List fonts with bold styles only
+ghostty +list-fonts --bold
+
+# Validate your config without starting Ghostty
+ghostty +validate-config
+```
+
+---
+
+## Configuration File Basics
+
+Configuration uses INI-style syntax:
+
+```ini
+option = value
+option = "quoted value with spaces"
+```
+
+### Key Points
+
+- **Repeatable options**: `font-family`, `font-feature`, `palette`, `env`, `config-file`, `command-palette-entry`, `custom-shader` can all be repeated.
+- **Empty string resets**: Set `option = ""` to clear previously set values.
+- **Config includes**: Use `config-file = "path"` to include additional config files.
+- **Optional includes**: Prepend `?` to suppress errors if file does not exist, for example `config-file = "?optional.conf"`.
+- **CLI overrides**: CLI arguments automatically clear config file values for the same option.
+
+### Special Prefixes for Commands
+
+- `direct:` — Bypass shell expansion (no glob, tilde, or argument parsing)
+- `shell:` — Force shell wrapping
+
+---
+
+## Quick Configuration Examples
+
+```ini
+# Font setup with fallback
+font-family = "JetBrains Mono"
+font-family = "Noto Sans Mono"   # fallback for symbols
+font-size = 12
+
+# Disable programming ligatures
+font-feature = -calt,-liga
+
+# Cursor
+cursor-style = block
+cursor-style-blink = false
+
+# Window padding
+window-padding-x = 2
+window-padding-y = 2
+
+# Palette
+palette-generate = true
+```
+
+---
+
+## Custom Shaders
+
+Ghostty supports Shadertoy-compatible GLSL shaders:
+
+```ini
+custom-shader = ~/.config/ghostty/shaders/vignette.glsl
+custom-shader-animation = true
+```
+
+Shaders receive uniforms for the terminal screen texture (`iChannel0`), cursor position, palette colors, and focus state.
+
+---
+
+## Default Keybindings
+
+| Keybind | Action |
+|---------|--------|
+| `ctrl+shift+,` | `reload_config` |
+| `ctrl+` / `ctrl+=` | `increase_font_size:1` |
+| `ctrl+-` | `decrease_font_size:1` |
+| `ctrl+0` | `reset_font_size` |
+| `ctrl+shift+f` | `start_search` |
+| `ctrl+shift+a` | `select_all` |
+| `ctrl+Enter` | `toggle_fullscreen` |
+| `ctrl+shift+P` | `toggle_command_palette` |
+
+See [Configuration Reference](configuration.md#appendix-default-keybindings) for the full table.
+
+---
+
+## Cross-References
+
+- See [Configuration Reference](configuration.md) for every option, organized by category.
+- The [AGENTS.md Format](../../core/agents-md-format.md) governs how agent behavior contracts reference this configuration.