acstack 0.0.0-stage → 0.47.0

package/assets/playwriter-bridge/vm-free-port.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# vm-free-port.sh – VM-side cleanup for a stuck reverse-forward port.
+#
+# When the Windows tunnel repeatedly hits "remote port forwarding failed
+# for listen port 19988", this script identifies what holds 127.0.0.1:19988
+# on the VM and – if safe – kills it.
+#
+# Guardrail: refuses to kill if the socket is held by the current user's
+# own interactive SSH session. Killing that would drop the shell running
+# the script.
+#
+# Guardrail: refuses to kill anything that still answers HTTP on the port. A
+# forward that is serving is the bridge, not litter, and the operator who runs
+# this out of habit would be taking the browser away from whoever is using it.
+#
+# Scoped strictly to the two ports this setup owns: 19988 (the bridge's CDP
+# port) and 19989 (the document opener). Any other port is refused. This is an
+# allowlist rather than a free --port flag on purpose - the guardrails below
+# reason about what a holder is, and that reasoning is only valid for sockets
+# we put there. Exits non-zero with a clear message on any ambiguous or unsafe
+# situation.
+#
+# Intended to be invoked via the handoff block produced by Windows-side
+# doctor.ps1. Safe to run at any time; no-ops if the port is already free.
+
+set -u
+
+PORT=19988
+# 64 for a bad argument (the conventional EX_USAGE), because 2 already means
+# something specific here: the port is held by something this script may not
+# kill. Reusing it would make "you typed it wrong" indistinguishable from "the
+# port is genuinely stuck".
+case "${1:-}" in
+    --port)
+        case "${2:-}" in
+            19988|19989) PORT="$2" ;;
+            *) printf 'ERROR: --port accepts only 19988 (bridge) or 19989 (opener), not "%s".\n' "${2:-}" >&2; exit 64 ;;
+        esac
+        ;;
+    "") ;;
+    *) printf 'usage: vm-free-port.sh [--port 19988|19989]\n' >&2; exit 64 ;;
+esac
+
+log() { printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*"; }
+err() { log "ERROR: $*" >&2; }
+
+# Inspect 127.0.0.1:$PORT – print owner PID, process name, and parent PID.
+find_holder() {
+    ss -H -lntp "sport = :$PORT" 2>/dev/null | head -n1
+}
+
+line=$(find_holder)
+if [ -z "$line" ]; then
+    log "port $PORT is already free. Nothing to do."
+    exit 0
+fi
+
+log "current holder: $line"
+
+# Guardrail: is the forward still carrying traffic? A holder on this port is not
+# garbage by default - while the tunnel is up it is the bridge, and this is the
+# socket agent-browser drives Chrome through. The question is asked of the port
+# rather than of the process, and asked first, because a non-root ss cannot name
+# the owner of someone else's socket: the checks below would give up at "could
+# not parse PID" and never reach the one guardrail that matters most. doctor.ps1 prints this
+# script as the remedy for an amber "Tunnel logs" row, and that row trails for
+# five minutes after the tunnel has already healed itself, so running the
+# clearer against a healthy forward is the ordinary mistake, not the rare one.
+#
+# Any HTTP answer counts as alive. A 401 or a 404 comes from a CDP endpoint
+# that is serving and merely guarded, or asked for a path it does not have, so
+# --fail is deliberately absent: it would read those as dead and kill them. The
+# probe is bounded at 3 seconds, because a genuinely wedged socket is exactly
+# the one that would otherwise hang the clearer called to free it.
+#
+# There is no override flag for this refusal, on purpose. A live tunnel is
+# released by closing the session holding it, and a switch that skipped the
+# probe would just be the habit the probe exists to stop.
+if curl -s -o /dev/null -m 3 "http://127.0.0.1:$PORT/" 2>/dev/null; then
+    err "port $PORT is carrying a live tunnel: something answered HTTP on it just now."
+    err "Killing the holder would take the browser away from whoever is using it."
+    err "If the tunnel really is finished with, close the SSH session holding the"
+    err "forward - on the laptop that is stop.ps1 - and this port frees itself."
+    exit 7
+fi
+
+# ss -lntp line format includes users:(("<name>",pid=<pid>,fd=<fd>))
+pid=$(printf '%s' "$line" | grep -oE 'pid=[0-9]+' | head -n1 | cut -d= -f2)
+if [ -z "${pid:-}" ]; then
+    err "could not parse PID from ss output. Run: sudo ss -lntp 'sport = :$PORT'"
+    exit 2
+fi
+
+pname=$(ps -o comm= -p "$pid" 2>/dev/null || true)
+ppid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ' || true)
+log "PID $pid ($pname), parent PID $ppid"
+
+# Guardrail: is this process part of the current user's active SSH session?
+# If the holder (or any ancestor) is our own sshd session leader, refuse.
+current_sid=$(loginctl show-session "$(loginctl | awk -v u="$(id -un)" '$3==u {print $1; exit}')" -p Leader --value 2>/dev/null || true)
+
+# Walk ancestors of the holder. If we meet $$ (this script's own shell) or
+# its session leader, it's us.
+own_tree=0
+cursor=$pid
+for _ in 1 2 3 4 5 6 7 8; do
+    [ -z "$cursor" ] && break
+    [ "$cursor" = "1" ] && break
+    if [ "$cursor" = "$$" ] || [ "$cursor" = "$PPID" ]; then
+        own_tree=1
+        break
+    fi
+    if [ -n "${current_sid:-}" ] && [ "$cursor" = "$current_sid" ]; then
+        own_tree=1
+        break
+    fi
+    cursor=$(ps -o ppid= -p "$cursor" 2>/dev/null | tr -d ' ' || true)
+done
+
+if [ "$own_tree" = "1" ]; then
+    err "port $PORT is held by your own interactive session (PID $pid, ancestor of this shell)."
+    err "Killing it would drop the SSH session running this script."
+    err "Exit this SSH session from another shell, or close the client, then retry."
+    exit 3
+fi
+
+# Prefer not to kill anything that is not sshd – surface it for review.
+if [ "$pname" != "sshd" ] && [ "$pname" != "sshd-session" ]; then
+    err "holder is '$pname', not sshd. Refusing to kill a non-sshd process on port $PORT."
+    err "If this is expected (e.g. a local test server), stop it manually."
+    exit 4
+fi
+
+# Check parent liveness: an orphan sshd forward channel typically has a
+# parent that has exited or has been re-parented.
+if [ -n "${ppid:-}" ] && [ "$ppid" != "1" ]; then
+    if ! kill -0 "$ppid" 2>/dev/null; then
+        log "parent PID $ppid is gone – holder is an orphan sshd forward channel."
+    else
+        log "parent PID $ppid is alive – holder is an active sshd session, likely a stale tunnel that has not yet been reaped by ClientAlive."
+    fi
+fi
+
+log "killing PID $pid ..."
+if kill "$pid" 2>/dev/null; then
+    :
+else
+    log "kill failed without privilege; retrying with sudo."
+    if ! sudo -n kill "$pid" 2>/dev/null; then
+        err "could not kill PID $pid. Re-run with sudo, or ask the admin to kill it."
+        exit 5
+    fi
+fi
+
+# Give the kernel a moment to release the socket.
+for _ in 1 2 3 4 5; do
+    sleep 1
+    if [ -z "$(find_holder)" ]; then
+        log "port $PORT is now free."
+        exit 0
+    fi
+done
+
+err "port $PORT still held after kill. Current state:"
+ss -lntp "sport = :$PORT" >&2 || true
+exit 6

package/assets/terminal-workspace/client-keybindings.md

@@ -0,0 +1,87 @@
+# Free the keys your terminal emulator swallows
+
+Hand this to a coding agent running **on the machine you type on** – the
+Windows, macOS, or Linux desktop you SSH *from*. You cannot do this from the
+remote host. The local terminal emulator intercepts the keys before they ever
+reach the other end.
+
+## 1. The emulator claims the same alt chords the remote host binds
+
+On the remote host the user runs herdr, a terminal multiplexer. One program
+holds many terminal sessions and keeps them running after the user
+disconnects. Its setup binds `alt` key combinations, called chords, for panes,
+tabs and popups.
+
+Some terminal emulators bind the same chords locally. They swallow the
+keypress, or they act on it **and** forward it, so one press does two things.
+
+The known collision is **`alt+shift+d`**, which Windows Terminal binds to
+"duplicate pane" by default. It splits the tab on your own machine and never
+forwards the key, so the remote host sees nothing.
+
+The remote setup avoids this one by putting its diff viewer on `alt+f` and
+`alt+shift+f`. Other emulators claim other chords, so the table below still
+has to be free.
+
+To tell an emulator collision from a remote misconfiguration, run `cat -v` in
+any pane and press the chord. One that arrives prints an escape sequence such
+as `^[Z`. One that prints nothing never left your machine.
+
+## 2. Unbind, in the terminal emulator only
+
+Work in the terminal emulator config only. Unbind every chord in the table
+below that the emulator currently claims. Change nothing on the remote host,
+and do not touch the remote configuration.
+
+| Chord | Used remotely for |
+|---|---|
+| `alt+f` / `alt+shift+f` | diff viewer, popup and tab |
+| `alt+x` / `alt+shift+x` | diff comparison picker, popup and tab |
+| `alt+i` / `alt+shift+i` | pull request dashboard, popup and tab |
+| `alt+y` / `alt+shift+y` | file manager, popup and tab |
+| `alt+g` / `alt+shift+g` | git TUI, popup and tab |
+| `alt+h` `alt+j` `alt+k` `alt+l` | move between panes |
+| `alt+left` / `alt+right` | previous and next tab |
+| `alt+up` / `alt+down` | previous and next workspace |
+| `alt+1` ... `alt+9` | jump to an agent |
+| `alt+c` `alt+e` `alt+minus` `alt+z` `alt+s` `alt+a` `alt+n` `alt+u` `alt+w` `alt+r` | new tab, splits, zoom, sidebar, last pane, agent and workspace navigation |
+
+A workspace is one herdr container holding tabs and panes.
+
+### Windows Terminal
+
+Settings, then "Open JSON file". Add to the `actions` array:
+
+```json
+{ "command": "unbound", "keys": "alt+shift+d" }
+```
+
+Windows Terminal binds three more chords from the same family. Check
+`alt+shift+plus`, `alt+shift+minus` and `alt+shift+<arrow>` in the same pass.
+
+### Other emulators
+
+- **WezTerm**: `keys` in `.wezterm.lua`, with `action = wezterm.action.DisableDefaultAssignment`
+- **iTerm2**: Preferences, Keys, Key Bindings, or the profile's own Keys tab
+- **kitty**: `map alt+shift+d no_op` in `kitty.conf`
+- **Ghostty**: `keybind = alt+shift+d=ignore` in the config
+- **GNOME Terminal / Konsole**: check the shortcut editor for the chord
+
+## 3. What never to change
+
+- **Back up the config before editing**, and show the change before saving.
+- Unbind only. Do not remap these chords to something else, and do not touch
+  bindings unrelated to the table above.
+
+- Leave a chord alone when the terminal emulator does not bind it locally.
+
+## 4. Confirm exactly one thing happens
+
+Reload or restart the terminal, then SSH in and press `alt+shift+f`. Exactly
+one thing should happen.
+
+A tab opens on the remote host. A local split, or both at once, means the
+unbind did not take.
+
+Report which chords the terminal emulator had bound, what changed, and how to
+undo it.

package/assets/terminal-workspace/config.example.yaml

@@ -0,0 +1,329 @@
+# ACStack terminal workspace.
+# Copy to ~/.config/acstack/terminal-workspace.yaml, edit, then run setup.sh apply.
+#
+# This is machine-level, not per-project. It installs binaries and writes
+# keybindings for your user, so it does not belong in acstack/project.yaml.
+#
+# What each component is, every key, and the traps worth knowing:
+# docs/terminal-workspace.md in the ACStack plugin.
+#
+# A key here never carries a hyphen, so gh-dash is gh_dash. The last two
+# blocks name a feature rather than a binary: markdown is acstack-md, and
+# remote is acstack-clip plus acstack-open.
+
+# Master switch. With this false, apply exits without installing anything.
+# It removes nothing either. Use setup.sh uninstall for that.
+enabled: true
+
+herdr:
+  enabled: true
+  # A terminal multiplexer. One program holds many terminal sessions and keeps
+  # them running after you disconnect.
+  #
+  # A chord is one key combination, such as alt+f. herdr normally wants a
+  # prefix key first. You press the prefix, release it, then press the second
+  # key. A chord modifier replaces those two steps with one combination.
+  #
+  # Keep "alt". It is the only family measured to work on both attach paths.
+  # ctrl+alt does reach herdr when you SSH in and run it on the remote host.
+  # But a Windows client attaching with `herdr --remote` never delivers it, so
+  # those chords go silently dead.
+  # Set "none" to keep herdr's default prefix-only keymap.
+  chord_modifier: alt
+  # A pane's scrollbar costs it a column. herdr counts that column inside the
+  # pane rect but tells the program in the pane it has the full width, so a
+  # full-screen app wraps one column early and every row drifts one column
+  # left of the row above it. Set true to take the scrollbar back; scrolling
+  # itself is unaffected either way, because the mouse wheel and copy mode do
+  # not use it.
+  pane_scrollbars: false
+  # A pane border carries the name of the agent running in it. Several agents
+  # in several panes is what this workspace is for, and an unlabelled pane does
+  # not say which agent it holds. Set false to take the labels off.
+  agent_labels_on_pane_borders: true
+  # How the agent panel orders its rows: "priority" puts the agents waiting on
+  # you at the top. Empty leaves herdr's own order alone.
+  agent_panel_sort: ""
+  # Where herdr draws a toast, its own short status message. "herdr" draws it
+  # in the terminal itself, which is the only route that survives SSH. Empty
+  # leaves herdr's own choice alone.
+  toast_delivery: ""
+  theme:
+    # The colour theme herdr paints. Empty writes no theme at all, so herdr
+    # keeps whatever it already uses.
+    name: ""
+    # One herdr server, two devices, two backgrounds. auto_switch asks the
+    # attached client for its background colour over OSC 11 - an escape
+    # sequence a terminal answers with the colour it is painting - and picks
+    # the dark or the light theme from the answer. So a dark terminal on one
+    # device and a light one on another, such as an e-ink panel, each get the
+    # right theme without either changing the other.
+    #
+    # Both keys below are read only when `light` names a theme. Without one
+    # there is nothing to switch to, so `name` is written on its own.
+    auto_switch: true
+    # The theme a light client gets. `name` is what a dark one gets, and what
+    # a client that answers nothing at all falls back to.
+    light: ""
+  worktrees_directory: "~/.herdr/worktrees"
+  # Agent state hook, so herdr reads state from the agent instead of the
+  # screen. One of: claude, codex, opencode, copilot, none.
+  integration: claude
+  # Link a small herdr plugin that keeps the sidebar numbers matching the keys
+  # you press for them. Opening or closing a workspace or a worktree moves the
+  # rows, so without this the number beside a row stops being the number that
+  # jumps to it.
+  renumber_plugin: true
+
+gh_dash:
+  enabled: true
+  # A pull request dashboard. It lists pull requests in the sections you
+  # define below, and hands the selected one to tuicr or to an agent.
+  popup_key: "alt+i"
+  tab_key: "alt+shift+i"
+  sections:
+    - title: Mine
+      filters: "is:open author:@me"
+    - title: Needs review
+      filters: "is:open review-requested:@me"
+    - title: Failing
+      filters: "is:open author:@me status:failure"
+  # Local clones. Needed for checkout and for {{.RepoPath}} in keybindings.
+  repo_paths: {}
+  # Bind PageUp and PageDown to scroll the preview. gh-dash uses ctrl+u and
+  # ctrl+d by default, which is fine in vim and awkward everywhere else.
+  page_keys: true
+  keybindings:
+    # Both keys below are what apply binds anyway with no config file present.
+    # Change either to move it, or set it to "" to leave the key unbound.
+    #
+    # Open the selected pull request in tuicr, which reviews it in place.
+    review: "D"
+    # Hand the selected pull request to an agent. Empty disables it.
+    agent_review: "S"
+
+diffnav:
+  enabled: true
+  # A diff viewer with a file tree. The popup compares the branch you are on
+  # against origin/dev, committed work only, and names both sides in a banner.
+  # Repos without a dev branch fall back to the default branch.
+  popup_key: "alt+f"
+  # Same comparison, a new tab instead of a popup.
+  tab_key: "alt+shift+f"
+  # An fzf menu of comparisons: against dev or the default branch, with or
+  # without uncommitted work, one commit, or any branch against any branch.
+  pick_key: "alt+x"
+  # Same menu, a new tab instead of a popup.
+  pick_tab_key: "alt+shift+x"
+
+delta:
+  enabled: true
+  # The diff renderer git pages through. Sets core.pager and
+  # interactive.diffFilter. This does not change what agents see, because git
+  # only pages to a terminal.
+  set_git_pager: true
+
+tuicr:
+  enabled: true
+  # Reviews a pull request inside the terminal. gh-dash hands pull requests to
+  # it. It is not the file manager, which is yazi below.
+  # Starting width of the file list, as a percentage of the content area.
+  file_list_width: 30
+  # Per-file +added -removed counts in the tree.
+  show_file_line_stats: true
+  # "dark", "light", or empty to let tuicr work it out for itself.
+  #
+  # Detection asks the terminal for its background colour over OSC 11 - an
+  # escape sequence a terminal answers with the colour it is painting. Under
+  # `herdr --remote` nothing answers, so tuicr falls back to a desktop setting
+  # that a headless machine reports as light, then paints dark text on a black
+  # terminal. Pin the value on any machine you reach over the network.
+  appearance: ""
+  #
+  # TEMPORARY. Two upstream pull requests are still open, plus one local fix
+  # with none yet:
+  #   agavra/tuicr#607  configurable file line stats  (antonio2368)
+  #   agavra/tuicr#633  <leader>L / <leader>H resize  (ours)
+  #   (none yet)        blank +/- counts in pull request review mode  (ours)
+  # Until both merge, the two settings above only exist in a fork build.
+  # `setup.sh status` checks both and tells you when to switch this off.
+  # With it false, the stock release installs and ignores those two settings.
+  build_from_fork: false
+  fork: "https://github.com/ac8318740/tuicr"
+  fork_branch: "local/daily"
+
+lazygit:
+  enabled: true
+  # A git TUI: stage with space, commit with c, amend with A, push with P.
+  # g is reserved for it, so herdr's goto sits on prefix+t instead.
+  popup_key: "alt+g"
+  # Same tool, a new tab instead of a popup.
+  tab_key: "alt+shift+g"
+
+harlequin:
+  enabled: true
+  # A SQL editor in the terminal. Write a query on the left, read the rows on
+  # the right, and browse the schema in a tree beside both.
+  #
+  # It is the one component that is not a downloaded binary. harlequin is a
+  # python program, so uv installs it into an environment of its own and puts
+  # one command on your PATH. A machine without uv skips this component and
+  # apply says so.
+  popup_key: "alt+q"
+  # Same editor, a new tab instead of a popup.
+  tab_key: "alt+shift+q"
+  # The databases harlequin can talk to. Each name here installs the
+  # harlequin-<name> package alongside it. Adding one and running apply again
+  # reinstalls harlequin with the new set.
+  adapters: [postgres, snowflake]
+  # Your connection profiles. acstack writes a starter file here the first time
+  # you press the key, and never writes it again - what is in it is yours.
+  #
+  #   default_profile = "local"
+  #
+  #   [profiles.local]
+  #   adapter = "postgres"
+  #   conn_str = "postgres://localhost:5432/postgres"
+  #
+  # A snowflake profile names an account, user, role, warehouse, database and
+  # schema, or a single connection_name pointing at a connection in
+  # ~/.snowflake/connections.toml. Prefer the second: it keeps the secret out
+  # of this file.
+  config_path: "~/.config/acstack/harlequin.toml"
+
+pi:
+  # Off by default, because it writes into pi's own config in ~/.pi/agent.
+  # pi is a coding agent in the terminal. Turning this on installs it with npm
+  # if it is missing, then installs ACStack into it, pinned to this plugin's
+  # version, with pi-subagents, which ACStack needs to launch a subagent.
+  #
+  # It also writes one line into pi's context file in ~/.pi/agent (AGENTS.md
+  # by default) that lets pi delegate when an ACStack skill says to.
+  # It sets "toolActivation": "eager" in
+  # ~/.pi/agent/extensions/subagent/config.json. It binds
+  # "app.message.dequeue" to "ctrl+enter" in ~/.pi/agent/keybindings.json.
+  # These changes sit beside your own settings, which stay.
+  #
+  # Logging in is yours: run pi, then /login.
+  enabled: false
+  # pi-compact-tools, which shortens how pi draws each tool call.
+  compact_tools: true
+  # billion-context, which adds context compression to pi. When bili is on
+  # PATH, apply also runs bili's native plugin setup for pi. Claude Code and
+  # Codex stay off bili.
+  billion_context: true
+  # Pi's question tool. rpiv-ask-user-question is used because it can show
+  # markdown, code and artifact previews beside a decision, accepts freeform
+  # answers and notes, and does not require a full-event telemetry env var.
+  question_tool: true
+  # rpiv-todo, which adds a todo tool to pi.
+  todo: true
+  # pi-plugin-manager, which adds pi plugin management commands.
+  plugin_manager: true
+  # pi-web-access, which adds web search, URL fetching, GitHub repo cloning,
+  # PDF extraction and media understanding tools to pi. This is separate from
+  # pi.settings.install_telemetry, which controls pi's anonymous install and
+  # update reporting and stays false in this example.
+  web_access: true
+  # pi-slash-anywhere, which lets slash commands run from any prompt.
+  slash_anywhere: true
+  # agentic-retro's pi extension, which queues each finished pi session for a
+  # retro. Needs the agentic-retro plugin installed first, and apply says so
+  # when it is not.
+  agentic_retro: true
+  # Written into ~/.pi/agent/settings.json. Empty leaves pi's own value alone.
+  # Every other key in that file stays as you set it, and disable puts back
+  # any value of yours that apply replaced.
+  settings:
+    # Hide the model's thinking in the transcript.
+    hide_thinking_block: true
+    # How pi draws a mermaid diagram: "off", "final", or "streaming".
+    # Quote it, because YAML reads a bare off as false.
+    mermaid: streaming
+    # pi's anonymous install and update reporting. Kept off by this setup.
+    install_telemetry: false
+    # A pi theme name. "system" takes its colours from the terminal.
+    theme: system
+
+neovim:
+  # The one component that is off by default, because it writes into a neovim
+  # config you built yourself. Every other one owns its files outright.
+  enabled: false
+  # LazyVim marks an unsaved buffer by recolouring the filename and nothing
+  # else, so a glance at the statusline cannot tell you a buffer is modified.
+  # Turning this on writes ~/.config/nvim/lua/plugins/acstack.lua, a whole
+  # file of acstack's own, which appends a dot to the statusline for a
+  # modified buffer, and makes copy work over SSH (osc52_clipboard below).
+  # It never edits a file you wrote, and
+  # `setup.sh disable neovim` deletes it again.
+  # Skipped on a machine with no LazyVim config, because both parts rely on
+  # LazyVim.
+  #
+  # The colour of the dot. The default is the catppuccin red.
+  unsaved_dot_color: "#f38ba8"
+  # Over SSH, :%y+ fails because neovim finds no clipboard. This sends every
+  # copy to the machine you sit at over OSC 52. Section 3.5 of
+  # docs/terminal-workspace.md covers paste. Left out when a file of yours
+  # already sets vim.g.clipboard.
+  osc52_clipboard: true
+
+yazi:
+  enabled: true
+  # A file manager. Markdown renders live in the preview pane through
+  # acstack-md, so a document draws as the cursor moves over it. Enter opens
+  # the same renderer full width, where more of a diagram fits.
+  # A popup, leaving the tab layout alone.
+  popup_key: "alt+y"
+  # Opens a real tab instead.
+  tab_key: "alt+shift+y"
+  # Opens the hovered file in $EDITOR. tuicr puts the editor on the same key
+  # in both its panels, so one key means edit across the workspace.
+  edit_key: "e"
+  # Sends the hovered file to your own browser.
+  browser_key: "b"
+  # Previews markdown as source, with line numbers down the left.
+  line_numbers_key: "#"
+  # Sends the hovered file to the machine you sit at, over Tailscale Taildrop.
+  # Set it to that machine's Tailscale node name, as `tailscale status` on this
+  # machine spells it. Empty writes no key at all.
+  # Both machines must sit on one tailnet under one Tailscale user account,
+  # because Taildrop refuses to cross either boundary.
+  download_target: ""
+  # The key that sends it. Only read when download_target is set.
+  download_key: "D"
+  show_hidden: true
+
+markdown:
+  enabled: true
+  # This component installs three tools: acstack-md, mermaid-ascii and glow.
+  # acstack-md draws a markdown file in the terminal, calling glow for the
+  # prose and mermaid-ascii for the diagrams. A mermaid diagram is a diagram
+  # written as text in the file itself. acstack-md can also serve the same
+  # file to a real browser, for the diagrams worth studying.
+  #
+  # Text rather than inline images is deliberate. herdr emits the kitty
+  # graphics protocol, and no terminal reachable over SSH from Windows or
+  # Android renders it, so an image never arrives. e-ink panels also render
+  # text far better than bitmaps. The fast refresh modes an interactive
+  # terminal needs are the ones that drop the greyscale depth an image needs.
+  #
+  # acstack-md --serve takes its port from $ACSTACK_MD_PORT and falls back to
+  # 6419. Forward whichever port you serve on, or the link --serve prints is
+  # unreachable from your laptop.
+
+remote:
+  enabled: true
+  # Copy and open, on a machine you reach over SSH.
+  #
+  # The dev machine – the remote machine your agents run on, a virtual machine
+  # in this setup – has no display and no clipboard. Anything that shells out
+  # to xclip fails, and xdg-open exits 1. Two programs close the gap.
+  # acstack-clip sends text to your own terminal's clipboard over OSC 52, an
+  # escape sequence a terminal reads as "put this text on the clipboard of the
+  # machine I am running on". acstack-open finds whatever browser is actually
+  # reachable.
+  #
+  # Install an xclip stand-in backed by acstack-clip. Programs that only know
+  # how to shell out – gh-dash's y and Y among them – then copy correctly.
+  # Skipped when the machine has a real xclip or a display of its own.
+  clipboard_shim: true