Map: integration key contract #8

Destination

A written spec of devdash's integration key contract: how an [[integrations]] table declares keys, how a key press reaches the command, where selection state lives between runs, focus and conflict rules (including user and integration overrides of r/q), where active keys are shown, and how a key-triggered run redraws. Implementable with no further decisions. General, with prompt-tutor's j/k/s as the acceptance example.

Notes

• Feature request: Integration keybindings: let integrations add and change keys. It closes when the spec is implemented, not when this map ends.
• Spec location: Digital Brain/Wiki/02-Projects/Devdash/, one file per spec named YYYY-MM-DD HHMM <Title>.md (more specs may follow). The vault rule puts plans and specs in the Wiki, not docs/. Glossary terms go in devdash's GLOSSARY.md; ADRs, only for hard-to-reverse trade-offs, go in docs/adr/.
• Every grilling ticket: call the Skill tool for grilling and domain-modeling.
• Grounding: devdash code is devdash.py (watch(), Integration, Dashboard). Today keys are read one byte at a time and lowercased; integrations run with stdin=DEVNULL in their own session. prompt-tutor --once accepts no selection or Scope input; the Watcher holds j/k/s state in-process.
• Execution carried into this map (Shayan, 2026-10-09): decisions made by the agent, then implemented on devdash feat/integration-keys and prompt-tutor feat/devdash-keys. Spec: Wiki/02-Projects/Devdash/2026-10-09 1112 Integration key contract.md.
• Tracker: GitHub sub-issues for tickets, native blocked_by dependencies for blocking.

Decisions so far

• Prior art: how terminal dashboards let plugins take keys: one-shot re-run per key with the selection passed in is the common pattern (k9s, lazygit, tmux); keys are scoped by context or focus, not required to be unique; no prior art for keys arriving during a run.
• Bindable keys: which key presses devdash can bind: printable ASCII + arrows/enter/tab, case-sensitive everywhere
• Delivery: how a key press reaches the integration command: re-run per press with DEVDASH_ACTION; one-shot contract unchanged
• State between runs: who remembers an integration's selection: integration owns state in a per-process DEVDASH_STATE_FILE
• Focus and conflicts: which section a key goes to: focus with tab; built-ins win; collisions with built-ins rejected; integrations may share keys
• Key-triggered runs: redraw, overlap, and errors: FIFO queue (8), serialized runs, immediate redraw, failed runs not retried
• Declaration: the integration key schema and built-in remaps: [keys] built-ins + per-integration key→action table
• Discoverability: where active keys appear: per-section key hints (bindings under each integration, r refresh under PRs), bottom row q quit/tab focus, no clock; headings count down to next fetch; ▸ focus marker

Not yet specified

None: the spec settles the remaining fog (glossary terms, --once behavior, failed action runs, README).

Out of scope

• Mouse input.