docs: teach the extension model with a four-step lesson

README.md

@@ -18,6 +18,10 @@ What it does:
 - **Agent skill.** An installable skill (Help ▸ Install Agent Skill…) teaches Claude Code or Codex the control model and the `agtermctl` commands, so an agent running inside agterm can build its own layout, run overlays, manage windows, and show images inline without you explaining the API.
 - **Agent status.** A coding agent reports its state (active, blocked, or completed) onto its session's row, so you can see which of many running agents needs you. Status hooks for Claude Code, Codex, Pi, OpenCode, and other agents install from Help ▸ Install Agent Status Hooks….
 
+A lot of "does it have X?" questions have the same answer: bind X yourself. A `command` line in `keymap.conf` turns any shell line into a key chord, and an overlay gives an interactive program a real terminal over the session, so a file manager, a git UI, or a database browser is one line away. Bigger workflows become scripts, which is what the [cookbook](cookbook/) collects.
+
+You are not meant to write those lines by hand. Install the agent skill (Help ▸ Install Agent Skill…) and ask the agent in your session for what you want, and it writes the line with the right syntax, targeting, and PATH handling. [Extend agterm](https://agterm.com/docs#extend) shows that, and teaches enough of the model to read and change what comes back.
+
 For the real terminal work, rendering, VT parsing, and shell I/O, `agterm` embeds [Ghostty](https://ghostty.org)'s engine (libghostty); everything above is `agterm`'s own.
 
 ![agterm](docs/screenshots/main.png)
@@ -33,7 +37,7 @@ An agent's interactive prompt mid-session, with attention glyphs on the sessions
 
 ![Agent prompt](docs/screenshots/agent-prompt.png)
 
-A file manager in a floating overlay over the active session:
+The yazi file manager in a floating overlay over the active session, from one `command` line in `keymap.conf`:
 
 ![Floating overlay](docs/screenshots/floating-overlay.png)
 

docs/backlog/edit-keymap-menu-hides-the-extension-mechanism.md

@@ -0,0 +1,24 @@
+---
+worth: later
+where: agterm/agtermApp+Menus.swift
+added: 2026-08-20
+---
+# File ▸ Edit Keymap… does not read as "add features"
+
+The seeded `keymap.conf` is the best explanation of custom commands anywhere in the project. It documents
+the `command` directive, the detached-no-TTY limit, the PATH rule, the context tokens, and ships the
+`agtermctl session overlay open 'zsh -lc lazygit'` pattern (`agtermCore/Sources/agtermCore/ConfigPaths.swift:39-116`).
+It is better than the public docs were before the `#extend` lesson, and a user reaches it only by opening
+a menu item named after key configuration.
+
+Both menu entries name the mechanism rather than what it is for: `File ▸ Edit Keymap…` and
+`Navigate ▸ Custom Commands`. A user looking for a file browser has no reason to open either. The docs
+side of this is fixed (the lesson, the nav rename, the screenshot captions); the in-app affordance is not.
+
+Worth considering, none of it obviously right: wording that advertises extension rather than
+configuration, a Help entry that points at the lesson, or seeding the palette with one commented example
+so `Custom Commands` is not empty on a fresh install. All of it is AppKit/menu work whose cost should be
+priced on its own, which is why it was kept out of the docs change.
+
+Surfaced while brainstorming the onboarding gap after a new user asked whether agterm has a file browser
+and the answer turned out to be one keymap line.

docs/backlog/seeded-lazygit-example-omits-target.md

@@ -0,0 +1,29 @@
+---
+worth: later
+where: agtermCore/Sources/agtermCore/ConfigPaths.swift:77
+added: 2026-08-20
+---
+# the seeded Lazygit example omits --target and can open its overlay elsewhere
+
+The starter `keymap.conf` ships:
+
+```
+command "Lazygit"  ctrl+a>g  agtermctl session overlay open 'zsh -lc lazygit' --socket "$AGT_SOCKET"
+```
+
+`TargetOptions.target` defaults to `active` (`agtermCore/Sources/agtermctlKit/Commands.swift:69`), and `active`
+is resolved when the request reaches the server, not when the chord built its context. The custom command is
+spawned detached and fire-and-forget (`agterm/Commands/CustomCommandRunner.swift:336`), so a session or window
+switch between the keypress and delivery opens the overlay over whatever is selected by then. The command
+reference already tells automated callers to pin it (`site/commands.html:379`), and a custom command has the
+stable `$AGT_SESSION_ID` for exactly this.
+
+The fix is one flag: `--target "$AGT_SESSION_ID"`. The line is otherwise valid — `overlay open` does not
+require a size flag, so omitting `--size-percent` correctly gives a full-size overlay.
+
+Worth doing because the `#extend` lesson now sends new users to **File ▸ Edit Keymap…**, where they read this
+example next to the docs' pinned one and get two different answers. Kept out of the docs change (#PR) because
+touching `ConfigPaths.swift` pulls in the full Swift gate run for a one-line seed-text improvement, and no
+existing user is blocked by it.
+
+Found by codex while reviewing the paste lines in the `#extend` lesson.