grilling-workbench 0.2.0 → 0.3.0

package/README.md

@@ -18,15 +18,21 @@ server or idle-chat wakeup service is included.
 From the project where you want to use the workbench:
 
 ```sh
-npx --yes grilling-workbench@0.2.0 install-skill
+npx skills@latest add PavingLayer/grilling-workbench \
+  --skill grilling-workbench --agent codex
 ```
 
-The installer creates `.agents/skills/grilling-workbench` and refuses to overwrite
-an existing skill. Codex detects new skills automatically; restart it if the skill
+The [Skills CLI](https://github.com/vercel-labs/skills) installs the skill from
+GitHub into `.agents/skills/grilling-workbench` and records its source in
+`skills-lock.json`. This command targets Codex; omit `--agent codex` to choose
+another agent. Codex detects new skills automatically; restart it if the skill
 does not appear. Explicit `$grilling-workbench` invocation can verify installation;
-normal interview use should select it automatically. npm caches the application;
-the skill and interview sessions remain in your project. Use the same pinned
-version for setup and every command in a round.
+normal interview use should select it automatically.
+
+`@latest` selects the skill installer version. The installed skill pins application
+commands to `grilling-workbench@0.3.0`, which npm fetches into its cache when run.
+Keep that exact application version throughout a round. The bundled `install-skill`
+command remains available for [exact-release and offline installation](docs/deployment.md#bundled-installer-for-an-exact-release).
 
 Source: [PavingLayer/grilling-workbench](https://github.com/PavingLayer/grilling-workbench).
 Package: [grilling-workbench on npm](https://www.npmjs.com/package/grilling-workbench).
@@ -39,15 +45,15 @@ explains skill discovery and project configuration alongside Matt Pocock's skill
 ## Agent workflow
 
 ```sh
-npx --yes grilling-workbench@0.2.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
-npx --yes grilling-workbench@0.2.0 serve --session .workbench/topic-r01
+npx --yes grilling-workbench@0.3.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
+npx --yes grilling-workbench@0.3.0 serve --session .workbench/topic-r01
 ```
 
 Keep the server process running. In a second persistent process, **before showing
 the URL returned by serve**:
 
 ```sh
-npx --yes grilling-workbench@0.2.0 wait --session .workbench/topic-r01
+npx --yes grilling-workbench@0.3.0 wait --session .workbench/topic-r01
 ```
 
 Keep the agent turn waiting on that process. The listener blocks on TCP and exits
@@ -68,6 +74,23 @@ screens. The footer keeps navigation and submission actions visible. Each questi
 shows its full wording, options, benefits, and trade-offs. Recommendations are
 labels; every question starts unanswered.
 
+The form supports arrow keys and Vim-style keyboard control. Use `↓` / `↑`
+(or `j` / `k`) to focus options and buttons, `Enter` or `Space` to activate them,
+and `←` / `→` (or `h` / `l`) to change questions. Moving focus does not select
+an option. Use Tab or Shift+Tab to reach the answer field; arrows move the text
+cursor normally while typing.
+`1`–`9` chooses or toggles an option; `i` focuses your answer or notes and `Esc`
+returns to navigation. `Ctrl+Enter` (or `Cmd+Enter`) submits the whole form,
+including while typing. `q` opens the question picker, `H` opens submission
+history, `b` toggles the sidebar, `d` moves on to answer later, and `x` clears the
+current answer and notes. `gg` / `G` focuses the first / last control, and
+`Ctrl+d` / `Ctrl+u` scrolls half a page. Dialogs keep navigation inside them.
+
+The footer shows Normal or Insert mode. Open **Keys ?** (or press `?` outside a
+text field) for the guide and an option to disable Vim shortcuts, remembered in
+this browser. Arrow navigation, Tab, Shift+Tab, Enter, Space, Esc, and
+Ctrl/Cmd+Enter remain available with Vim shortcuts turned off.
+
 Choices and notes save as drafts while you work. Drafts survive navigation,
 reloads, and question updates. If a question's meaning changes, the app retains
 your earlier answer and asks you to revisit the new wording. Save failures offer
@@ -76,7 +99,7 @@ retry and recovery options.
 **Submit form** sends the entire round in one click, including edits still being
 saved. Questions left blank are reported as `not_answered`. Each submission keeps
 the exact question versions and answers; retries reuse its identity to prevent
-duplicates. Drafts become submitted outcomes only when you click Submit.
+duplicates. Drafts become submitted outcomes only when you explicitly submit the form.
 
 After saving, the server delivers the submission to the waiting agent over a
 socket. Unacknowledged forms replay after a reconnect, and the page shows when the

package/docs/deployment.md

@@ -1,6 +1,6 @@
 # Local deployment
 
-Version 0.2.0 ships on public npm with a CLI, static browser files,
+Version 0.3.0 ships on public npm with a CLI, static browser files,
 a demo questionnaire, operational docs, and the integration skill. It needs Node
 22+ and no production dependencies or build service. Linux with Node 22.22.2 was
 verified locally. CI is configured for Node 22 and 24 on Linux; other operating
@@ -11,14 +11,20 @@ systems have not been release-tested.
 Run this from any project, including a non-Node project:
 
 ```sh
-npx --yes grilling-workbench@0.2.0 install-skill
-npx --yes grilling-workbench@0.2.0 --version
+npx skills@latest add PavingLayer/grilling-workbench \
+  --skill grilling-workbench --agent codex
+npx --yes grilling-workbench@0.3.0 --version
 ```
 
-npm fetches the application into its execution cache. Only the installed skill
-and the sessions you create live in the consuming project; no project dependency
-or global installation is required. Keep `@0.2.0` on every command so the skill,
-server, and listener use the same release. npm needs registry access on first use;
+The [Skills CLI](https://github.com/vercel-labs/skills) installs the skill from
+GitHub into `.agents/skills/grilling-workbench` and records its source in
+`skills-lock.json`. The command targets Codex; omit `--agent codex` to choose
+another agent. No project dependency or global installation is required.
+
+`@latest` selects the installer version; the skill pins the application to `0.3.0`.
+The version check above fetches that application into npm's execution cache.
+Keep `@0.3.0` on every application command so the server and listener use the
+release required by the skill. Initial setup needs npm registry and GitHub access;
 use an explicit archive installation when reliable offline availability matters.
 
 Source and releases are maintained at
@@ -26,25 +32,35 @@ Source and releases are maintained at
 The public npm package is
 [grilling-workbench](https://www.npmjs.com/package/grilling-workbench).
 
+### Bundled installer for an exact release
+
+To install the skill bundled with a specific application release, use:
+
+```sh
+npx --yes grilling-workbench@0.3.0 install-skill
+```
+
+Run this from each project that should discover it. The default target is
+`.agents/skills/grilling-workbench`. `--target DIR` supports another host's skill
+directory. This command copies the bundled skill; it does not edit AGENTS.md,
+install upstream skills, or overwrite existing skills. This installer does not
+create a Skills CLI lockfile.
+
 If you prefer a project dependency:
 
 ```sh
-npm install --save-dev --save-exact grilling-workbench@0.2.0
+npm install --save-dev --save-exact grilling-workbench@0.3.0
 npx --no grilling-workbench install-skill
 ```
 
 Or explicitly install the executable globally:
 
 ```sh
-npm install --global grilling-workbench@0.2.0
+npm install --global grilling-workbench@0.3.0
 grilling-workbench --version
+grilling-workbench install-skill
 ```
 
-Run the setup command from each project that should discover it.
-The default target is `.agents/skills/grilling-workbench`. `--target DIR` supports
-another host's skill directory. This command copies the bundled skill; it does
-not edit AGENTS.md, install upstream skills, or overwrite existing skills.
-
 ### Offline archives and maintainer releases
 
 From a clean source checkout:
@@ -58,7 +74,7 @@ mkdir -p dist
 npm pack --pack-destination dist
 ```
 
-The result is `dist/grilling-workbench-0.2.0.tgz`. The explicit package allowlist
+The result is `dist/grilling-workbench-0.3.0.tgz`. The explicit package allowlist
 excludes sessions, receipts, development dependencies, and tests. The package
 tests exercise both an offline project installation and `npx` execution from an
 isolated cache, including full form delivery, updates, shutdown, and restart.
@@ -67,7 +83,7 @@ Building the archive does not publish it.
 Offline consumers can install the archive as a project dependency or globally:
 
 ```sh
-npm install --offline --save-dev /absolute/path/grilling-workbench-0.2.0.tgz
+npm install --offline --save-dev /absolute/path/grilling-workbench-0.3.0.tgz
 npx --no grilling-workbench install-skill
 ```
 
@@ -78,7 +94,7 @@ Maintainers publish the checked archive to npm and attach the same file to its
 GitHub release. After the source commit is pushed and GitHub checks pass:
 
 ```sh
-npm publish ./dist/grilling-workbench-0.2.0.tgz --access public
+npm publish ./dist/grilling-workbench-0.3.0.tgz --access public
 ```
 
 Publication requires an authenticated npm account with publishing access. For
@@ -94,8 +110,8 @@ an absolute path when resuming from another directory. `init` refuses any existi
 directory, so it cannot reset a previous form accidentally.
 
 ```sh
-npx --yes grilling-workbench@0.2.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
-npx --yes grilling-workbench@0.2.0 serve --session .workbench/topic-r01
+npx --yes grilling-workbench@0.3.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
+npx --yes grilling-workbench@0.3.0 serve --session .workbench/topic-r01
 ```
 
 Both servers bind exclusively to `127.0.0.1`. By default the OS assigns free HTTP
@@ -154,9 +170,14 @@ new exact package version, compare its bundled skill with the installed copy, an
 restart `serve` at that version against the same directory. Update a local or
 global installation explicitly if you use one. To inspect a skill upgrade without overwriting
 customizations, use `install-skill --target /path/to/new-empty-directory` and merge
-changes deliberately. State schema 1 is retained in 0.2.0; unsupported state
+changes deliberately. State schema 1 is retained in 0.3.0; unsupported state
 versions and corrupt files fail without resetting answers.
 
+When upgrading a skill through the Skills CLI, review its changes and use the
+exact application version required by the updated skill for subsequent rounds.
+Finish active rounds with their original skill instructions and application
+version before upgrading.
+
 Back up `config.json`, `questions.json`, `session.json`, and `chat-receipts.json`
 with the server and receipt writer stopped. Restore those files into a private
 session directory, then start serve. Do not restore `runtime.json` or lock files;

package/docs/integration.md

@@ -14,16 +14,22 @@ and agent must run on the same computer.
 From the project where you want to use it:
 
 ```sh
-npx --yes grilling-workbench@0.2.0 install-skill
+npx skills@latest add PavingLayer/grilling-workbench \
+  --skill grilling-workbench --agent codex
 ```
 
-This fetches the application into npm's cache and installs the instructions that
-teach the agent when and how to use it. It creates `.agents/skills/grilling-workbench`
-and preserves any existing skill at that path. No `package.json`, project
-dependency, or global installation is required, including in non-Node projects.
-The skill uses the same pinned package version for subsequent commands.
+The [Skills CLI](https://github.com/vercel-labs/skills) fetches the skill from GitHub
+and installs the instructions that teach the agent when and how to use the
+workbench. For Codex, it creates `.agents/skills/grilling-workbench` and records the
+source in `skills-lock.json`. Omit `--agent codex` to choose another agent.
+No `package.json`, project dependency, or global installation is required,
+including in non-Node projects.
 
-For offline installation, source development, or upgrades, use the
+`@latest` applies to the skill installer. The skill pins application commands to
+`grilling-workbench@0.3.0`; npm downloads that application into its cache when the
+agent first runs it. Keep the same exact application version throughout a round.
+
+For exact-release or offline installation, source development, or upgrades, use the
 [deployment guide](deployment.md). Keep your existing interview skills installed;
 Matt Pocock's repository has its own [installation instructions](https://github.com/mattpocock/skills).
 
@@ -84,8 +90,8 @@ the workbench.
 First check whether `grilling-workbench` appears in the agent's available skills.
 In Codex, that list combines applicable project skills, user skills, administrator
 and system skills, and enabled plugin skills. It does not automatically include
-local skills from unrelated projects. Our installer adds the workbench at the
-current project's `.agents/skills/grilling-workbench` path.
+local skills from unrelated projects. The setup command above adds the workbench
+at the current project's `.agents/skills/grilling-workbench` path.
 
 Codex normally detects new skills automatically. If it is missing, restart Codex
 and check the installed path. If it appears more than once, inspect the source
@@ -105,7 +111,7 @@ rules. It is optional; the skill already defines the interview trigger.
 Whenever interviewing the user, use the grilling-workbench skill at
 `.agents/skills/grilling-workbench/SKILL.md`. Apply it alongside the current
 interview workflow, including grill-me, without requiring a request for a browser
-form. The command is `npx --yes grilling-workbench@0.2.0`.
+form. The command is `npx --yes grilling-workbench@0.3.0`.
 
 Read the skill's operating protocol before presenting questions. Keep reasoning,
 clarification, and decision records in the existing workflow. Respect an explicit
@@ -135,11 +141,9 @@ explanations about an existing option should continue in chat.
 ## Share it with another project
 
 Share [PavingLayer/grilling-workbench](https://github.com/PavingLayer/grilling-workbench)
-and repeat the one-command setup above. npm includes the matching application and
-skill; browser and command-execution tools must be supplied by the agent host.
-
-The repository also exposes `skills/grilling-workbench/SKILL.md` in a layout
-recognized by the [Skills CLI](https://github.com/vercel-labs/skills#skill-discovery).
-The npm `install-skill` command is the primary setup path because it bundles the
-skill with the same exact application release. Offline users can instead share
-the release archive; see [distribution and installation](deployment.md#distribution-and-installation).
+and repeat the Skills CLI setup above. The skill supplies the pinned application
+command; browser and command-execution tools must be supplied by the agent host.
+
+The bundled npm `install-skill` command remains an alternative when you want the
+skill from an exact application release or need an offline archive. See
+[distribution and installation](deployment.md#distribution-and-installation).

package/docs/release-0.3.0.md

@@ -0,0 +1,28 @@
+Forms can now be completed with arrow keys or Vim-style shortcuts, including
+question navigation, answer selection, notes, submission, history, and recovery
+actions.
+
+- Use Up/Down to focus controls, Left/Right to change questions, and Enter or
+  Space to activate. Arrow navigation also works with Vim shortcuts disabled.
+- Vim keys include j/k, h/l, gg/G, numbered choices, i to write, and Escape to
+  return to navigation. Ctrl/Cmd+Enter submits the whole form while typing.
+- A visible keyboard guide and mode indicator explain the controls. The Vim
+  preference is remembered in the browser.
+- Focus survives saved edits and question updates. Dialog navigation stays
+  inside the dialog; text fields retain normal cursor and selection keys.
+- Installation guidance now uses the Skills CLI to install the agent skill
+  directly from GitHub. Bundled application commands are pinned to 0.3.0.
+
+Requires Node.js 22 or later. No production dependencies were added. State schema
+1 and socket protocol 1 are unchanged; existing drafts and submissions remain
+compatible. Finish active rounds on their original application version before
+upgrading.
+
+```sh
+npx --yes grilling-workbench@0.3.0 --version
+```
+
+Validation includes 27 automated tests, offline-install and npx package smoke
+tests, and embedded-browser checks. The validation guide records the remaining
+browser and platform coverage limits. The attached archive is the npm package
+artifact.

package/docs/validation.md

@@ -6,12 +6,24 @@ use the [deployment guide](deployment.md).
 
 ## Automated checks
 
-The 0.2.0 release checks passed locally on Linux with Node.js 22.22.2 on September
+Version 0.3.0 adds arrow and Vim keyboard navigation, focus preservation, and a
+shortcut guide. State schema 1 and socket protocol 1 are unchanged. Keyboard
+checks and remaining browser-validation limits are recorded below.
+
+The 0.3.0 release passed a clean `npm ci`, syntax validation, all 27 tests, and
+both offline-install and npx package smoke tests locally on Linux with Node.js
+22.22.2 on September 6, 2026. GitHub Actions runs the release checks on Node 22
+and 24 for the published source commit.
+
+The 0.2.0 and 0.2.1 release checks passed locally on Linux with Node.js 22.22.2 on September
 6, 2026 (UTC): syntax validation, 18 automated tests, and both installed-package
 and `npx` smoke tests. CI runs the same checks on Node 22 and 24; see
 [GitHub Actions](https://github.com/PavingLayer/grilling-workbench/actions/workflows/verify.yml)
 for the hosted results associated with a release commit.
 
+Version 0.2.1 updates the installation guides and matching package version pins.
+The application code, state schema, and socket protocol are unchanged from 0.2.0.
+
 The automated tests cover:
 
 - Unanswered defaults, recommendation labels, and 1,000 generated action histories
@@ -28,14 +40,72 @@ The automated tests cover:
 
 The package smoke test packs the actual release and exercises it twice: installed
 offline in an unrelated project, and through `npx` from an isolated cache in a
-project without package files or dependencies. Both modes verify skill
+project without package files or dependencies. Both modes verify bundled skill
 installation without overwriting an existing copy, two isolated sessions, served
 browser assets, whole-form delivery, acknowledgments, definition updates, restart,
 and the source-checkout demo entrypoint. The `npx` test uses the local archive,
 so registry publication and a fresh registry download are separate release checks.
 
+The recommended Skills CLI installation was separately checked on September 6,
+2026 (UTC), with Skills CLI 1.5.23 and Node.js 22.22.2. In a clean temporary project,
+`npx skills@latest add PavingLayer/grilling-workbench --skill grilling-workbench --agent codex`
+was run with confirmation accepted through `--yes`. It installed the skill and
+both reference files matching the repository, created `skills-lock.json`, and
+added no `package.json`, `package-lock.json`, or `node_modules`. The installed
+skill retained its `grilling-workbench@0.2.0` application pin. This check verifies
+installation, not automatic selection by an agent.
+
 ## Embedded-browser checks
 
+### Vim keyboard controls
+
+The keyboard-control change passed syntax validation, all 24 automated tests,
+and both package smoke tests on September 6, 2026. Six keyboard tests exercise
+an answer-and-submit workflow, dialog isolation, `gg` timing and focus resets,
+held-key suppression for mutations, composition and native-key passthrough,
+disabled shortcuts, and command mappings. The package tests verify that the
+new keyboard module is included and served by the installed application.
+
+An isolated demo session was checked in the embedded browser at the default
+1280×720 viewport and at 320×740, using the keyboard for:
+
+- Moving focus without selecting, selecting a radio with Enter, and toggling
+  multiple choices with number keys and Space; focus survives saved edits.
+- Entering multiline notes containing shortcut characters, leaving Insert mode,
+  and submitting all three question types directly from the text field.
+- Navigating the question picker, opening submission history, expanding submitted
+  answers, and focusing and scrolling the submitted text. Question navigation
+  and submission shortcuts do not act behind an open dialog.
+- Disabling Vim shortcuts, reloading to verify the remembered setting, then
+  using Tab, Enter, and Space to reopen the guide and enable them again.
+- Opening the narrow-screen question picker, inspecting the shortcut guide
+  without horizontal overflow, and returning focus when dialogs close.
+- Expanding an earlier answer and keeping it after a definition refresh;
+  clearing an answer and its notes; and moving on with Answer later.
+- Reaching both recovery actions during a simulated save failure, then retrying
+  successfully after restoring the question definitions. The recovery download
+  control was activated, but the embedded runner did not report a download event;
+  recovery-file delivery was not verified in this keyboard pass.
+
+The browser checks are manual integration evidence; the automated keyboard tests
+cover the command interpreter rather than browser focus or layout. Screen-reader
+and non-Chromium keyboard checks remain outstanding.
+
+### Earlier interface checks
+
+The arrow-navigation follow-up passed syntax validation, all 27 tests, and both
+package smoke tests on September 6, 2026. Three additional tests cover arrow
+navigation with Vim enabled and disabled, native cursor/selection and modifier
+behavior, and dialog isolation. Standard activation, Escape, and Ctrl/Cmd+Enter
+also remain available when Vim shortcuts are disabled.
+
+In a separate embedded-browser demo, Up/Down moved focus without changing radio
+answers, Enter and Space selected radios and checkboxes, and Left/Right changed
+questions. Tab reached multiline text; arrows and Shift+Arrow moved and selected
+text without changing questions. With Vim disabled, arrow navigation, dialog
+isolation, and submission from the text field were verified. The user's demo was
+refreshed after its save indicator reported Saved.
+
 The implemented interface has been checked in the embedded browser for:
 
 - A 20-question form at 808×1139, with independently scrolling navigation and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grilling-workbench",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local question forms with whole-form submission and event-driven agent delivery",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,7 @@
   "scripts": {
     "dev": "node src/dev.js",
     "start": "node src/dev.js",
-    "check": "node --check bin/grilling-workbench.js && node --check src/dev.js && node --check src/cli.js && node --check src/runtime.js && node --check src/core.js && node --check src/server.js && node --check src/storage.js && node --check src/delivery.js && node --check src/monitor.js && node --check src/submission-socket.js && node --check public/app.js",
+    "check": "node --check bin/grilling-workbench.js && node --check src/dev.js && node --check src/cli.js && node --check src/runtime.js && node --check src/core.js && node --check src/server.js && node --check src/storage.js && node --check src/delivery.js && node --check src/monitor.js && node --check src/submission-socket.js && node --check public/app.js && node --check public/keyboard.js",
     "test": "node --test test/*.test.js",
     "test:package": "node scripts/test-package.js && node scripts/test-package.js --npx"
   },

package/public/app.js

@@ -1,4 +1,5 @@
 import { transition, draftFor, questionById, hasAnswer, isStale, statusFor, progress, formSubmitted, makeReview as makeSubmission, formatSubmission } from '/core.js';
+import { createKeyboard } from '/keyboard.js';
 
 const app = document.querySelector('#app');
 const dialog = document.querySelector('#app-dialog');
@@ -6,6 +7,9 @@ const escape = value => String(value ?? '').replace(/[&<>"']/g, char => ({ '&':
 let state, version, currentId, running = false, error = '', conflict = false, connectionWarning = '';
 let pending = [], shownSubmission = null, receivedIds = new Set();
 let toastTimer, modalMode = '', refreshing = false, sidebarCollapsed = false;
+let dialogReturnFocus = null;
+let vimEnabled = true;
+try { vimEnabled = localStorage.getItem('workbench-vim') !== 'off'; } catch { /* Storage can be unavailable in embedded browsers. */ }
 const narrowViewport = matchMedia('(max-width: 640px)');
 const iconPaths = {
   check: '<circle cx="12" cy="12" r="9"/><path d="m8 12 3 3 5-6"/>',
@@ -18,6 +22,35 @@ const iconPaths = {
 };
 const icon = name => `<svg class="icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false">${iconPaths[name]}</svg>`;
 
+function rememberFocus(root) {
+  const element = document.activeElement;
+  if (!element || !root.contains(element)) return null;
+  const attribute = ['id', 'data-action', 'data-go', 'data-modal', 'data-submission'].find(name => element.hasAttribute(name));
+  if (!attribute) return null;
+  const region = element.closest('.footer-bar, #sidebar-questions');
+  const prefix = region ? (region.id ? `#${region.id} ` : '.footer-bar ') : '';
+  return {
+    selector: `${prefix}[${attribute}="${CSS.escape(element.getAttribute(attribute))}"]`,
+    selection: element.id === 'answer-text' ? [element.selectionStart, element.selectionEnd, element.selectionDirection] : null,
+  };
+}
+
+function restoreFocus(saved, root = document) {
+  const element = saved && root.querySelector(saved.selector);
+  if (!element || element.disabled || !element.getClientRects().length) return false;
+  element.focus({ preventScroll: true });
+  if (saved.selection) element.setSelectionRange(...saved.selection);
+  return true;
+}
+
+function replaceContent(element, html) {
+  if (element.innerHTML === html) return;
+  const focused = rememberFocus(element), scroll = element.scrollTop;
+  element.innerHTML = html;
+  element.scrollTop = scroll;
+  if (focused && !restoreFocus(focused)) focusControl(document.querySelector('#question-title'));
+}
+
 function toast(message) {
   const notice = document.querySelector('#notice');
   notice.textContent = message;
@@ -59,7 +92,7 @@ function renderChrome() {
   document.querySelector('#compact-progress').textContent = `${stats.answered} of ${stats.total} answered · ${formSubmitted(state) ? 'Form submitted' : `${stats.total - stats.answered} not answered`}`;
   const sidebar = document.querySelector('#sidebar-questions');
   const list = questionItems();
-  if (sidebar.innerHTML !== list) { const scroll = sidebar.scrollTop; sidebar.innerHTML = list; sidebar.scrollTop = scroll; }
+  replaceContent(sidebar, list);
   document.querySelector('#question-badges').innerHTML = badge(currentId);
   document.querySelector('[data-action="clear"]').disabled = !hasAnswer(draftFor(state, currentId));
   document.querySelector('#history-button').textContent = `Submissions (${state.submissions.length})`;
@@ -68,7 +101,7 @@ function renderChrome() {
   document.querySelector('#submit-form').disabled = conflict || pending.some(item => item.action.type === 'submit');
   const warning = document.querySelector('#save-warning');
   warning.hidden = !error && !connectionWarning;
-  warning.innerHTML = warning.hidden ? '' : `<p>${escape(error || connectionWarning)} Your work in this tab is retained. Unsaved changes will be lost if you close or reload it.</p><button class="button small" data-action="${conflict ? 'load-saved' : 'retry'}">${conflict ? 'Load saved version…' : 'Retry saving'}</button><button class="button small" data-action="recover">Download recovery copy</button>`;
+  replaceContent(warning, warning.hidden ? '' : `<p>${escape(error || connectionWarning)} Your work in this tab is retained. Unsaved changes will be lost if you close or reload it.</p><button class="button small" data-action="${conflict ? 'load-saved' : 'retry'}">${conflict ? 'Load saved version…' : 'Retry saving'}</button><button class="button small" data-action="recover">Download recovery copy</button>`);
 }
 
 function oldAnswer(draft) {
@@ -77,8 +110,7 @@ function oldAnswer(draft) {
 
 function render() {
   if (!state) return;
-  const focused = document.activeElement;
-  const textFocus = focused?.id === 'answer-text' ? { start: focused.selectionStart, end: focused.selectionEnd } : null;
+  const focused = rememberFocus(app);
   const mainScroll = document.querySelector('.main')?.scrollTop || 0;
   const sidebarScroll = document.querySelector('#sidebar-questions')?.scrollTop || 0;
   currentId = questionById(state, currentId) ? currentId : state.questionnaire.questions[0].id;
@@ -92,15 +124,16 @@ function render() {
     <main class="main"><div class="form-content"><p class="compact-progress" id="compact-progress"></p>
     <div id="save-warning" class="alert" role="alert" hidden></div>
     <article class="question-sheet" id="question" aria-labelledby="question-title"><div class="question-meta"><span class="question-position">Question ${index + 1} of ${state.questionnaire.questions.length}</span><button class="button small question-selector" id="question-selector" data-action="questions" aria-haspopup="dialog" aria-controls="app-dialog">Question ${index + 1} of ${state.questionnaire.questions.length} <span aria-hidden="true">▾</span></button><span id="question-badges"></span></div><h1 id="question-title" tabindex="-1">${escape(q.title)}</h1><p class="question-context">${escape(q.context)}</p>
-    ${stale ? `<div class="alert"><p><strong>This question was updated.</strong> Your earlier answer is kept below. ${canAdopt ? 'Review the new wording, then keep or edit your answer.' : 'An earlier choice is no longer available. Choose a new answer to continue.'}</p><details><summary>Earlier question and answer</summary><div class="old-answer">${escape(oldAnswer(draft))}</div></details>${canAdopt ? '<button class="button small" data-action="adopt">Keep my answer with this wording</button>' : ''}</div>` : ''}
-    ${q.type !== 'text' ? `<p class="answer-hint">${q.type === 'single' ? 'Choose one, or write your own answer below.' : 'Choose any that apply, or write your own answer below.'}</p><fieldset class="options" aria-labelledby="question-title">${q.options.map(o => `<label class="option ${draft.optionIds.includes(o.id) ? 'selected' : ''}" id="option-${escape(q.id)}-${escape(o.id)}"><span class="option-top"><input type="${q.type === 'single' ? 'radio' : 'checkbox'}" name="answer-option" value="${escape(o.id)}" ${draft.optionIds.includes(o.id) ? 'checked' : ''} aria-labelledby="label-${escape(q.id)}-${escape(o.id)}"><span class="option-title" id="label-${escape(q.id)}-${escape(o.id)}">${escape(o.label)}</span>${o.recommended ? '<span class="badge recommended">Recommended</span>' : ''}</span><div class="option-body"><p class="option-description">${escape(o.description)}</p><div class="tradeoffs"><p><strong class="offers">${icon('check')} Offers</strong><span>${escape(o.benefit)}</span></p><p><strong class="tradeoff">${icon('balance')} Trade-off</strong><span>${escape(o.tradeoff)}</span></p></div></div></label>`).join('')}</fieldset>` : ''}
-    <label for="answer-text" class="field-label">${q.type === 'text' ? 'Your answer' : 'Your answer <span class="optional">In your own words</span>'}</label><textarea id="answer-text" maxlength="20000" rows="${q.type === 'text' ? 7 : 3}">${escape(draft.text)}</textarea>
+    ${stale ? `<div class="alert"><p><strong>This question was updated.</strong> Your earlier answer is kept below. ${canAdopt ? 'Review the new wording, then keep or edit your answer.' : 'An earlier choice is no longer available. Choose a new answer to continue.'}</p><details><summary id="earlier-answer">Earlier question and answer</summary><div class="old-answer">${escape(oldAnswer(draft))}</div></details>${canAdopt ? '<button class="button small" data-action="adopt">Keep my answer with this wording</button>' : ''}</div>` : ''}
+    ${q.type !== 'text' ? `<p class="answer-hint">${q.type === 'single' ? 'Choose one, or write your own answer below.' : 'Choose any that apply, or write your own answer below.'}</p><fieldset class="options" aria-labelledby="question-title">${q.options.map((o, optionIndex) => `<label class="option ${draft.optionIds.includes(o.id) ? 'selected' : ''}" id="option-${escape(q.id)}-${escape(o.id)}"><span class="option-top"><input id="answer-option-${escape(q.id)}-${escape(o.id)}" type="${q.type === 'single' ? 'radio' : 'checkbox'}" name="answer-option" value="${escape(o.id)}" ${draft.optionIds.includes(o.id) ? 'checked' : ''} aria-labelledby="label-${escape(q.id)}-${escape(o.id)}"><span class="option-title" id="label-${escape(q.id)}-${escape(o.id)}">${escape(o.label)}</span>${optionIndex < 9 ? `<kbd class="option-key" aria-hidden="true">${optionIndex + 1}</kbd>` : ''}${o.recommended ? '<span class="badge recommended">Recommended</span>' : ''}</span><div class="option-body"><p class="option-description">${escape(o.description)}</p><div class="tradeoffs"><p><strong class="offers">${icon('check')} Offers</strong><span>${escape(o.benefit)}</span></p><p><strong class="tradeoff">${icon('balance')} Trade-off</strong><span>${escape(o.tradeoff)}</span></p></div></div></label>`).join('')}</fieldset>` : ''}
+    <label for="answer-text" class="field-label">${q.type === 'text' ? 'Your answer' : 'Your answer <span class="optional">In your own words</span>'}</label><textarea id="answer-text" aria-describedby="answer-keyboard-hint" maxlength="20000" rows="${q.type === 'text' ? 7 : 3}">${escape(draft.text)}</textarea><p class="field-hint" id="answer-keyboard-hint">Type normally. <kbd>Esc</kbd> returns to navigation.</p>
     <div class="question-actions"><button class="button" data-action="defer">${icon('clock')}Answer later</button><button class="button" data-action="clear" ${hasAnswer(draft) ? '' : 'disabled'}>${icon('clear')}Clear answer</button></div></article></div></main>
-    </div><footer class="footer-bar"><nav class="footer-buttons ${index === state.questionnaire.questions.length - 1 ? 'last-question' : ''}" aria-label="Question navigation"><button class="button previous-question" ${index > 0 ? `data-go="${escape(state.questionnaire.questions[index - 1].id)}"` : 'disabled'} aria-label="Previous question">${icon('left')}<span>Previous</span></button><button class="button ${index === state.questionnaire.questions.length - 1 ? 'primary' : ''}" id="submit-form" data-action="submit">${icon('check')}Submit form</button>${index < state.questionnaire.questions.length - 1 ? `<button class="button primary" data-go="${escape(state.questionnaire.questions[index + 1].id)}">Next question ${icon('right')}</button>` : ''}</nav></footer>`;
+    </div><footer class="footer-bar"><div class="keyboard-bar"><span id="keyboard-mode" class="keyboard-mode" role="status"></span><span class="keyboard-hint"><kbd>↑</kbd> / <kbd>↓</kbd> move · <kbd>←</kbd> / <kbd>→</kbd> questions</span><button class="keyboard-help" data-action="keys" aria-haspopup="dialog" aria-controls="app-dialog">Keys <kbd>?</kbd></button></div><nav class="footer-buttons ${index === state.questionnaire.questions.length - 1 ? 'last-question' : ''}" aria-label="Question navigation"><button class="button previous-question" ${index > 0 ? `data-go="${escape(state.questionnaire.questions[index - 1].id)}"` : 'disabled'} aria-label="Previous question">${icon('left')}<span>Previous</span></button><button class="button ${index === state.questionnaire.questions.length - 1 ? 'primary' : ''}" id="submit-form" data-action="submit">${icon('check')}Submit form</button>${index < state.questionnaire.questions.length - 1 ? `<button class="button primary" data-go="${escape(state.questionnaire.questions[index + 1].id)}">Next question ${icon('right')}</button>` : ''}</nav></footer>`;
   renderChrome();
   document.querySelector('.main').scrollTop = mainScroll;
   document.querySelector('#sidebar-questions').scrollTop = sidebarScroll;
-  if (textFocus) { const field = document.querySelector('#answer-text'); field.focus({ preventScroll: true }); field.setSelectionRange(textFocus.start, textFocus.end); }
+  if (focused && !restoreFocus(focused)) focusControl(document.querySelector('#question-title'));
+  updateKeyboardMode();
 }
 
 function stage(action, redraw = true) {
@@ -175,18 +208,21 @@ app.addEventListener('click', event => {
   if (action === 'submit') submitForm();
   if (action === 'questions') showQuestions();
   if (action === 'history') showHistory();
+  if (action === 'keys') showKeys();
   if (action === 'recover') downloadRecovery();
   if (action === 'retry') retry();
   if (action === 'load-saved') loadSaved();
 });
 
 function openDialog(html, mode) {
+  const focused = dialog.open && modalMode === mode ? rememberFocus(dialog) : null;
+  if (!dialog.open) dialogReturnFocus = rememberFocus(document);
   modalMode = mode;
   dialog.innerHTML = html;
   if (!dialog.open) dialog.showModal();
   const heading = dialog.querySelector('#dialog-title');
   heading.tabIndex = -1;
-  heading.focus({ preventScroll: true });
+  if (!restoreFocus(focused, dialog)) heading.focus({ preventScroll: true });
 }
 const dialogHead = (title, description = '') => `<div class="dialog-head"><div><h2 id="dialog-title">${title}</h2>${description ? `<p>${description}</p>` : ''}</div><button class="close" data-modal="close" aria-label="Close dialog">×</button></div>`;
 
@@ -205,6 +241,104 @@ function questionItems() {
   }).join('');
 }
 
+function showKeys() {
+  const shortcuts = [
+    ['↓ / ↑', 'Focus the next / previous option or button'],
+    ['← / →', 'Previous / next question'],
+    ['j / k', 'Focus the next / previous option or button'],
+    ['gg / G', 'Focus the first / last control'],
+    ['Enter / Space', 'Activate the focused control'],
+    ['h / l', 'Previous / next question'],
+    ['1–9', 'Choose or toggle an option'],
+    ['i', 'Write your answer or notes'],
+    ['Esc', 'Leave the text field or close a dialog'],
+    ['Ctrl / ⌘ + Enter', 'Submit the entire form, including while typing'],
+    ['Ctrl + d / u', 'Scroll down / up half a page'],
+    ['q', 'Open the question picker'],
+    ['H', 'Open submission history'],
+    ['b', 'Toggle the sidebar or open the question picker'],
+    ['d', 'Answer later'],
+    ['x', 'Clear this answer and its notes'],
+    ['?', 'Open this guide'],
+  ];
+  openDialog(`${dialogHead('Keyboard shortcuts', 'Arrow keys and Vim-style navigation. Typing in the answer field uses your normal text editing keys.')}<div class="dialog-body"><p>Use <kbd>↓</kbd> / <kbd>↑</kbd> or <kbd>j</kbd> / <kbd>k</kbd> to reach every form action, including recovery and updated answers. Movement focuses options; <kbd>Enter</kbd> or <kbd>Space</kbd> selects them. In dialogs, navigation stays inside the dialog. Use <kbd>Tab</kbd> / <kbd>Shift + Tab</kbd> to reach text fields and other controls.</p><dl class="shortcut-list">${shortcuts.map(([keys, description]) => `<div><dt><kbd>${keys}</kbd></dt><dd>${description}</dd></div>`).join('')}</dl><label class="shortcut-setting"><input id="vim-enabled" type="checkbox" ${vimEnabled ? 'checked' : ''}> Enable Vim shortcuts</label><p class="field-hint">Arrow navigation, Tab, Enter, Space, Esc, and Ctrl / ⌘ + Enter also work with Vim shortcuts turned off.</p></div><div class="dialog-foot"><button class="button primary" data-modal="close">Back to form</button></div>`, 'keys');
+}
+
+const isEditing = element => element?.matches('textarea, select, input:not([type="radio"]):not([type="checkbox"]):not([type="button"]):not([type="submit"])') || element?.isContentEditable;
+
+function updateKeyboardMode() {
+  document.body.classList.toggle('vim-disabled', !vimEnabled);
+  const mode = document.querySelector('#keyboard-mode');
+  if (mode) mode.textContent = !vimEnabled ? 'Vim off' : isEditing(document.activeElement) ? 'Insert' : 'Normal';
+}
+
+function keyboardControls() {
+  const selector = 'button:not(:disabled), input[type="radio"], input[type="checkbox"], summary, a[href], [tabindex="0"]';
+  const controls = [...(dialog.open ? dialog : app).querySelectorAll(selector)].filter(element =>
+    !element.disabled && element.getClientRects().length && (dialog.open || !element.closest('.sidebar')));
+  // Start with dialog content; closing remains reachable at the end.
+  return dialog.open ? [...controls.filter(el => !el.matches('.close')), ...controls.filter(el => el.matches('.close'))] : controls;
+}
+
+function focusControl(element) {
+  element?.focus({ preventScroll: true });
+  element?.scrollIntoView({ block: 'nearest' });
+}
+
+function runKeyboardCommand(command, value) {
+  if (command === 'move' || command === 'edge') {
+    const controls = keyboardControls(), index = controls.indexOf(document.activeElement);
+    const next = command === 'edge' ? (value < 0 ? 0 : controls.length - 1)
+      : index < 0 ? (value > 0 ? 0 : controls.length - 1) : Math.max(0, Math.min(controls.length - 1, index + value));
+    return focusControl(controls[next]);
+  }
+  if (command === 'activate') {
+    const element = document.activeElement;
+    if (element?.matches('button:not(:disabled), input[type="radio"], input[type="checkbox"], summary, a[href]') && (!dialog.open || dialog.contains(element))) element.click();
+    return;
+  }
+  if (command === 'scroll') {
+    const focused = document.activeElement;
+    const candidates = dialog.open ? [focused?.closest('.export-text, .question-list'), dialog] : [document.querySelector('.main')];
+    const pane = candidates.find(element => element && element.scrollHeight > element.clientHeight);
+    pane?.scrollBy({ top: value * pane.clientHeight / 2, behavior: 'instant' });
+    return;
+  }
+  if (command === 'leave-edit') return focusControl(document.querySelector('#question-title'));
+  if (command === 'close') return dialog.close();
+  if (command === 'help') return showKeys();
+  if (!state) return;
+  if (command === 'navigate') {
+    const questions = state.questionnaire.questions, index = questions.findIndex(q => q.id === currentId);
+    if (questions[index + value]) navigate(questions[index + value].id);
+  }
+  if (command === 'choose') {
+    const option = document.querySelectorAll('input[name="answer-option"]')[value];
+    if (option) { focusControl(option); option.click(); }
+  }
+  if (command === 'edit') focusControl(document.querySelector('#answer-text'));
+  if (command === 'submit') document.querySelector('#submit-form:not(:disabled)')?.click();
+  if (command === 'questions') showQuestions();
+  if (command === 'history') showHistory();
+  if (command === 'sidebar') document.querySelector('#toggle-sidebar').click();
+  if (command === 'clear' || command === 'defer') document.querySelector(`[data-action="${command}"]:not(:disabled)`)?.click();
+}
+
+const keyboard = createKeyboard({
+  context: () => ({ enabled: vimEnabled, editing: isEditing(document.activeElement), modal: dialog.open }),
+  run: runKeyboardCommand,
+});
+document.addEventListener('keydown', keyboard.keydown);
+document.addEventListener('focusin', () => { keyboard.reset(); updateKeyboardMode(); });
+document.addEventListener('focusout', () => queueMicrotask(updateKeyboardMode));
+window.addEventListener('blur', keyboard.reset);
+dialog.addEventListener('change', event => {
+  if (event.target.id !== 'vim-enabled') return;
+  vimEnabled = event.target.checked;
+  try { localStorage.setItem('workbench-vim', vimEnabled ? 'on' : 'off'); } catch { /* The toggle still works for this tab. */ }
+  updateKeyboardMode();
+});
+
 function updateSidebarToggle() {
   document.body.classList.toggle('sidebar-collapsed', sidebarCollapsed);
   const toggle = document.querySelector('#toggle-sidebar');
@@ -224,7 +358,7 @@ function submitForm() {
   if (conflict || pending.some(item => item.action.type === 'submit')) return;
   let snapshot;
   try {
-    // Capture exactly what is in the form at the explicit click, including edits
+    // Capture exactly what is in the form at explicit submission, including edits
     // still saving. The existing queue persists those edits before this snapshot.
     snapshot = makeSubmission(state, crypto.randomUUID(), new Date().toISOString());
   } catch (failure) {
@@ -261,7 +395,7 @@ async function refreshReceipt() {
 
 function showSubmission(submission) {
   shownSubmission = submission;
-  openDialog(`${dialogHead('Form submitted', 'Your entire form is saved. You can continue in chat without copying or pasting anything.')}<div class="dialog-body"><div class="success-symbol" aria-hidden="true">✓</div><p id="delivery-status" role="status"></p><details class="submission-details"><summary>View submitted form</summary><pre class="export-text">${escape(formatSubmission(submission))}</pre></details></div><div class="dialog-foot"><button class="button primary" data-modal="close">Back to form</button></div>`, 'submission');
+  openDialog(`${dialogHead('Form submitted', 'Your entire form is saved. You can continue in chat without copying or pasting anything.')}<div class="dialog-body"><div class="success-symbol" aria-hidden="true">✓</div><p id="delivery-status" role="status"></p><details class="submission-details"><summary id="submitted-form-details">View submitted form</summary><pre class="export-text" tabindex="0" aria-label="Submitted form text">${escape(formatSubmission(submission))}</pre></details></div><div class="dialog-foot"><button class="button primary" data-modal="close">Back to form</button></div>`, 'submission');
   render(); renderReceipt(); void refreshReceipt();
 }
 
@@ -272,22 +406,23 @@ function showHistory() {
 
 dialog.addEventListener('click', async event => {
   const go = event.target.closest('[data-go]');
-  if (go) { dialog.close(); navigate(go.dataset.go); return; }
+  if (go) { dialogReturnFocus = { selector: '#question-title' }; dialog.close(); navigate(go.dataset.go); return; }
   const prior = event.target.closest('[data-submission]');
   if (prior) return showSubmission(state.submissions.find(s => s.id === prior.dataset.submission));
   const action = event.target.closest('[data-modal]')?.dataset.modal;
   if (action === 'close') dialog.close();
   if (action === 'history') showHistory();
+  if (action === 'keys') showKeys();
   if (action === 'recover') downloadRecovery();
   if (action === 'retry') { modalMode = 'saving'; retry(); }
 
 });
 dialog.addEventListener('close', () => {
-  const wasQuestionPicker = modalMode === 'questions';
+  if (dialog.open) return;
   modalMode = '';
-  const candidates = wasQuestionPicker ? ['#question-selector', '#toggle-sidebar'] : ['#submit-form:not(:disabled)', '#history-button:not([hidden])', '#toggle-sidebar'];
-  const returnTarget = candidates.map(selector => document.querySelector(selector)).find(element => element?.getClientRects().length);
-  returnTarget?.focus({ preventScroll: true });
+  if (!restoreFocus(dialogReturnFocus)) document.querySelector('#question-title')?.focus({ preventScroll: true });
+  dialogReturnFocus = null;
+  updateKeyboardMode();
 });
 
 function downloadRecovery() {

package/public/keyboard.js

@@ -0,0 +1,50 @@
+// Keep command interpretation separate from DOM focus and form mutations.
+export function createKeyboard({ context, run, now = Date.now }) {
+  let firstG = null;
+  const reset = () => { firstG = null; };
+  function keydown(event) {
+    const { enabled, editing, modal } = context();
+    if (event.defaultPrevented || event.isComposing || event.keyCode === 229 || event.altKey) return reset();
+    const key = event.key;
+    let command, value;
+    if (event.ctrlKey || event.metaKey) {
+      reset();
+      if (key === 'Enter' && !event.shiftKey && !modal) command = 'submit';
+      else if (enabled && event.ctrlKey && !event.metaKey && !event.shiftKey && !editing && ['d', 'u'].includes(key)) {
+        command = 'scroll'; value = key === 'd' ? 1 : -1;
+      } else return;
+    } else if (editing) {
+      reset();
+      if (key !== 'Escape') return;
+      command = 'leave-edit';
+    } else {
+      const previousG = firstG;
+      reset();
+      if (!event.shiftKey && (key === 'ArrowDown' || key === 'ArrowUp')) { command = 'move'; value = key === 'ArrowDown' ? 1 : -1; }
+      else if (!event.shiftKey && (key === 'ArrowLeft' || key === 'ArrowRight')) {
+        if (modal) return;
+        command = 'navigate'; value = key === 'ArrowRight' ? 1 : -1;
+      }
+      else if (key === 'Enter' && !event.shiftKey) command = 'activate';
+      else if (key === 'Escape') command = modal ? 'close' : 'leave-edit';
+      else if (!enabled) return;
+      else if (key === 'g') {
+        if (event.repeat) { event.preventDefault(); return; }
+        if (previousG !== null && now() - previousG < 1000) { command = 'edge'; value = -1; }
+        else { firstG = now(); event.preventDefault(); return; }
+      } else if (key === 'G') { command = 'edge'; value = 1; }
+      else if (key === 'j' || key === 'k') { command = 'move'; value = key === 'j' ? 1 : -1; }
+      else if (!modal) {
+        if (key === 'h' || key === 'l') { command = 'navigate'; value = key === 'l' ? 1 : -1; }
+        else if (/^[1-9]$/.test(key)) { command = 'choose'; value = Number(key) - 1; }
+        else command = { i: 'edit', q: 'questions', H: 'history', b: 'sidebar', d: 'defer', x: 'clear', '?': 'help' }[key];
+      }
+    }
+    if (!command) return;
+    event.preventDefault();
+    // Holding a key may move the cursor, but must not toggle, clear or submit twice.
+    if (event.repeat && !['move', 'navigate', 'scroll'].includes(command)) return;
+    run(command, value);
+  }
+  return { keydown, reset };
+}

package/public/styles.css

@@ -24,7 +24,7 @@ button, a, input, textarea { touch-action: manipulation; }
 button { cursor: pointer; border: 0; background: none; color: inherit; }
 button:disabled { cursor: not-allowed; opacity: .42; }
 a { color: inherit; text-decoration: none; }
-button:focus-visible, a:focus-visible, input:focus-visible, textarea:focus-visible, summary:focus-visible {
+button:focus-visible, a:focus-visible, input:focus-visible, textarea:focus-visible, summary:focus-visible, [tabindex="0"]:focus-visible {
   outline: 3px solid #57b3bf; outline-offset: 3px;
 }
 p { line-height: 1.55; margin: 0 0 1rem; }
@@ -90,6 +90,7 @@ h3 { font-size: 1rem; }
 .option:last-child { border-bottom: 0; }
 .option:hover { background: #f8fbfb; }
 .option.selected { background: #f0f9f9; box-shadow: inset 3px 0 var(--blue); }
+.option:has(input:focus-visible) { outline: 3px solid #57b3bf; outline-offset: -3px; }
 .option-top { display: flex; align-items: flex-start; gap: 12px; flex-wrap: wrap; }
 .option input { accent-color: var(--blue); height: 22px; width: 22px; flex: 0 0 22px; margin: 1px 0 0; }
 .option-title { font-size: 1.0625rem; line-height: 1.4; font-weight: 600; flex: 1; min-width: 120px; }
@@ -113,6 +114,19 @@ textarea::placeholder { color: #7c878c; }
 .button.small { padding: 6px 10px; min-height: 34px; }
 .question-actions .button { min-width: 145px; }
 .footer-bar { background: white; border-top: 1px solid #cbd3d7; padding: 19px 22px max(19px, env(safe-area-inset-bottom)); z-index: 5; }
+.keyboard-bar { display: flex; align-items: center; gap: 12px; margin: -8px 0 10px; font-size: .75rem; color: var(--muted); }
+.keyboard-mode { font-size: .6875rem; font-weight: 650; text-transform: uppercase; letter-spacing: .04em; color: var(--blue); }
+.keyboard-help { margin-left: auto; padding: 4px 6px; border-radius: 3px; white-space: nowrap; }
+.keyboard-help:hover { background: var(--blue-soft); }
+kbd { font: inherit; font-family: ui-monospace, monospace; border: 1px solid var(--line); border-radius: 3px; padding: 1px 4px; white-space: nowrap; }
+.option-key { color: var(--muted); font-size: .75rem; margin-top: 3px; }
+.field-hint { font-size: .75rem; color: var(--muted); margin: 8px 0 0; }
+.shortcut-list { margin: 20px 0; }
+.shortcut-list > div { display: grid; grid-template-columns: 155px minmax(0, 1fr); gap: 14px; padding: 10px 0; border-bottom: 1px solid var(--line); font-size: .875rem; line-height: 1.5; }
+.shortcut-list dd { margin: 0; }
+.shortcut-setting { display: flex; align-items: center; gap: 10px; font-size: .875rem; }
+.shortcut-setting input { width: 20px; height: 20px; accent-color: var(--blue); }
+.vim-disabled .option-key { display: none; }
 .footer-buttons { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 30px; }
 .footer-buttons.last-question { grid-template-columns: repeat(2, minmax(0, 1fr)); }
 .footer-buttons .button { min-height: 46px; }
@@ -196,6 +210,8 @@ dialog::backdrop { background: #111c2470; }
   .toast { bottom: 90px; }
 }
 @media (max-width: 420px) {
+  .keyboard-hint { display: none; }
+  .shortcut-list > div { grid-template-columns: 1fr; gap: 7px; }
   .topbar { grid-template-columns: 146px minmax(0, 1fr); }
   .brand-area { padding: 0 8px; gap: 2px; }
   .brand { font-size: .9375rem; }

package/skills/grilling-workbench/SKILL.md

@@ -19,10 +19,10 @@ skill on its own.
 Before presenting a round, read [the agent protocol](references/agent-protocol.md).
 When authoring or changing questions, read [the question format](references/questions.md).
 
-Run `npx --yes grilling-workbench@0.2.0` for every CLI command. This uses the
+Run `npx --yes grilling-workbench@0.3.0` for every CLI command. This uses the
 public npm package maintained at `https://github.com/PavingLayer/grilling-workbench`
 without adding a project dependency. Check `--version`; this skill ships with
-package 0.2.0 and socket protocol 1. Keep the exact version throughout a round;
+package 0.3.0 and socket protocol 1. Keep the exact version throughout a round;
 do not use `@latest` or an unversioned command. An explicitly configured local or
 global installation is also supported when its version matches. If installation
 or registry access fails, report it rather than substituting manual copy/paste.

package/skills/grilling-workbench/references/agent-protocol.md

@@ -1,6 +1,6 @@
 # Agent protocol
 
-Use `npx --yes grilling-workbench@0.2.0` throughout the round. An explicitly
+Use `npx --yes grilling-workbench@0.3.0` throughout the round. An explicitly
 configured local or global executable at the same version is also supported.
 Commands emit JSON to stdout, diagnostics/readiness to stderr, and exit nonzero on
 failure. No command makes model calls or writes to the chat or issue tracker.
@@ -11,9 +11,9 @@ failure. No command makes model calls or writes to the chat or issue tracker.
    `.workbench/checkout-design-r01`. This names one chat's round, not a global inbox.
 
    ```sh
-   npx --yes grilling-workbench@0.2.0 validate --questions /absolute/path/round.json
-   npx --yes grilling-workbench@0.2.0 init --session .workbench/checkout-design-r01 --questions /absolute/path/round.json
-   npx --yes grilling-workbench@0.2.0 serve --session .workbench/checkout-design-r01
+   npx --yes grilling-workbench@0.3.0 validate --questions /absolute/path/round.json
+   npx --yes grilling-workbench@0.3.0 init --session .workbench/checkout-design-r01 --questions /absolute/path/round.json
+   npx --yes grilling-workbench@0.3.0 serve --session .workbench/checkout-design-r01
    ```
 
    Keep `serve` running in a persistent process session. Wait for its `ready` JSON;
@@ -24,7 +24,7 @@ failure. No command makes model calls or writes to the chat or issue tracker.
 2. Start a second persistent process before showing the form:
 
    ```sh
-   npx --yes grilling-workbench@0.2.0 wait --session .workbench/checkout-design-r01
+   npx --yes grilling-workbench@0.3.0 wait --session .workbench/checkout-design-r01
    ```
 
    The command authenticates to this session's loopback TCP socket. The stderr
@@ -52,7 +52,7 @@ failure. No command makes model calls or writes to the chat or issue tracker.
 5. Once the snapshot is in the current agent's context, record receipt:
 
    ```sh
-   npx --yes grilling-workbench@0.2.0 ack SUBMISSION_ID --session .workbench/checkout-design-r01
+   npx --yes grilling-workbench@0.3.0 ack SUBMISSION_ID --session .workbench/checkout-design-r01
    ```
 
    Use the actual returned ID. Never auto-ack inside the listener or before the
@@ -70,7 +70,7 @@ failure. No command makes model calls or writes to the chat or issue tracker.
 `init` copies the source definitions into the session. To revise the live form:
 
 ```sh
-npx --yes grilling-workbench@0.2.0 update --session .workbench/checkout-design-r01 --questions /absolute/path/revised-round.json
+npx --yes grilling-workbench@0.3.0 update --session .workbench/checkout-design-r01 --questions /absolute/path/revised-round.json
 ```
 
 Keep the questionnaire ID for the same round. The command validates and atomically

package/src/server.js

@@ -8,7 +8,7 @@ import { readReceipts } from './delivery.js';
 export { atomicWrite } from './storage.js';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const publicFiles = { '/': ['public/index.html', 'text/html'], '/app.js': ['public/app.js', 'text/javascript'], '/styles.css': ['public/styles.css', 'text/css'], '/core.js': ['src/core.js', 'text/javascript'] };
+const publicFiles = { '/': ['public/index.html', 'text/html'], '/app.js': ['public/app.js', 'text/javascript'], '/keyboard.js': ['public/keyboard.js', 'text/javascript'], '/styles.css': ['public/styles.css', 'text/css'], '/core.js': ['src/core.js', 'text/javascript'] };
 
 export function createWorkbenchServer({ dataDir = join(root, '.workbench'), questionsPath = join(root, 'data/questions.json'), write = atomicWrite } = {}) {
   const statePath = join(dataDir, 'session.json');