docs: teach the extension model with a four-step lesson - #471
Merged
Conversation
keymap.conf is agterm's extension mechanism, but docs.html shelved it under SCRIPTING after the agtermctl reference, behind a heading that named key configuration. A user wanting one key that opens a file browser has no reason to look there and does not think he is scripting. Move the section to sit after Customization and rename it "Custom commands & keys". Content is unchanged; the diff is a relocation.
A new user asked whether agterm has a file browser. It does, as one keymap line, and nothing in the docs put that within reach: overlays were explained eleven hundred lines from the `command` directive, and the cookbook's recipes nearly all ship a script, so there was no rung between the five nouns and a full workflow. Add an "Extend agterm" section between Install and the concepts tour. Four steps, each naming the building block it adds: session context, the overlay, the control API, then asking an agent that has the bundled skill. That last step reframes the skill from driving agterm during automation to customizing it, which no public copy said. The paste lines pin --target, --workspace and --window: a custom command is spawned detached, so `active` resolves on arrival and can land in whatever the user switched to. Overlay programs are wrapped in `zsh -lc`, the only way a terminal-spawned program reaches a Homebrew binary (#393 widened the runner's PATH, not the terminal's). Name yazi in the floating-overlay captions in README and index.html, where the question actually forms. Two findings kept out of scope go to docs/backlog: the in-app menu wording, and the seeded Lazygit example's missing --target.
The lesson had the skill as step 4 titled "Or have an agent write it for you", which reads as a fallback for people who dislike config files. It is the intended route: the skill carries the keymap syntax, the command catalog, the context tokens and the PATH rule, so an agent that has it writes a working line where one without it writes a plausible broken one. State that before step 1 rather than after step 4, and drop the "Or" from the heading. Keep the step itself last: the three steps before it are what let a reader judge the line that comes back and change it later, which is the reason for the order and not a ranking. Same inversion in the README, where it was a trailing clause.
Deploying agterm with
|
| Latest commit: |
931a6a8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://2c10635d.agterm.pages.dev |
| Branch Preview URL: | https://docs-crash-course.agterm.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
a new user asked whether agterm has a file browser. It does, as one keymap line, and nothing in the docs put that within reach. Overlays were explained at
site/docs.html:770and thecommanddirective at:1895, eleven hundred lines apart, under a nav heading that named key configuration rather than extension. The cookbook is the closest thing to teaching material, but 26 of its 28 recipes ship a script, so there was no rung between the five nouns and a full workflow.adds an "Extend agterm" section between Install and the concepts tour. Four steps, each naming the building block it adds: session context, the overlay, the control API, then asking an agent that has the bundled skill. That last step reframes the skill from driving agterm during automation to customizing it, which no public copy said before.
the paste lines are pinned on purpose. A custom command is spawned detached, so a bare
--targetresolvesactivewhen the request reaches the server rather than when the chord fired, and the overlay can open in whatever the user switched to. Same onsession newfor--windowand--workspace, plus--no-selectso the comment matches what the line does. Overlay programs are wrapped inzsh -lc: #393 widened the PATH the custom-command runner uses, not the one a terminal-spawned program gets.first commit is a pure relocation of the keymap section, 715/713 lines, content unchanged apart from the heading. Read it separately from the second and the diff stays reviewable.
also names yazi in the floating-overlay captions in README and
site/index.html, which is where the question actually forms.two findings kept out of scope, both written up in
docs/backlog/: the in-app menu wording (File > Edit Keymap...does not read as "add features"), and the seeded Lazygit example's own missing--target.docs only, no Swift touched. HTML structure validated on both files, and the relocation was checked byte-identical against 042f239 apart from the heading.