Make F1 open a complete, up-to-date User Guide #83

New Issue

hugo · 2026-08-30T20:58:56Z

hugo commented

2026-08-30 20:58:56 +00:00

Bug

The Help menu's bundled user guide is not discoverable through the standard F1 help shortcut, and the guide no longer describes the capabilities visible in the current app.

Current behavior:

Help > DS4Server Help uses ⇧⌘/ in src/native_menu.rs.
docs/USER_GUIDE.md is embedded into the app and shown in the help window.
The guide incorrectly says that there is no built-in extension installer, while Preferences > Agent Extensions can already install portable Codex plugins from HTTPS Git repositories and manage them.
A2UI is only mentioned at a high level, without explaining its available components or how users ask for and interact with a surface.
Important capabilities are scattered through the guide rather than presented as an onboarding path a new user can read from start to finish.

This leaves new users without a reliable overview of what DS4Server can do or how to access it.

Required fix

1. Use F1 for the User Guide

Rename the Help menu entry to DS4Server User Guide.
Replace the current ⇧⌘/ accelerator with unmodified F1 using the native menu accelerator.
F1 and the menu item must use the existing OpenHelp path: open one help window, or focus the existing help window instead of creating duplicates.
Do not add a global event monitor or custom key listener. The native menu accelerator is the source of truth.
On Macs whose system settings map the top row to media/brightness controls, the user may need to press fn-F1; DS4Server must not override the system mapping.
Update every shortcut reference in the bundled guide so the displayed documentation and native menu agree.

2. Turn the bundled help into a complete user guide

Rewrite and expand docs/USER_GUIDE.md as user-facing documentation for the shipped application. Keep it readable in the existing scrollable Markdown help window; no help-window redesign is required.

Organize it so a fresh user can follow it in order:

Getting started
- Install or select a supported model in Model Manager.
- Add a project.
- Start a chat, choose a thinking profile and permission mode, and send the first prompt.
- Explain that models, chats, project references, configuration, and extension data stay local.
Projects, chats, and context
- Creating, switching, renaming, pinning, archiving, deleting, exporting, stopping, and queuing prompts.
- Concurrent chats and the single shared model runtime.
- Context usage, compaction, checkpoints, and context rebuilds after model/runtime changes.
Agent capabilities and safety
- Explain, in user language, the available categories: file listing/reading/searching, writing/editing, shell commands, web search/page visits, Git work, approvals, Ralph loops, workspace instructions, standard skills, and Dev Brain.
- Clearly distinguish content search, filename discovery once the native glob tool is available, and shell execution. Do not document issue #82 as shipped until it is actually implemented.
- Explain permission modes, what triggers approval, cancellation, structured tool errors, and saved large tool output.
Agent extensions
- Replace the obsolete statement that no installer exists.
- Document Preferences > Agent Extensions and the complete current workflow:
  - install from an HTTPS Git repository;
  - optionally pin a branch, tag, or commit;
  - the repository must be a portable Codex plugin with .codex-plugin/plugin.json and at least skills or supported lifecycle hooks;
  - inspect the displayed source, resolved commit, author, version, skill count, and hooks;
  - enable/disable, manually update, and uninstall;
  - command hooks require an explicit trust confirmation and run with the user's permissions despite DS4Server's environment, timeout, and output limits;
  - hook failures are shown on the extension;
  - explain when changes affect the current chat versus when a fresh chat/restart is needed, based on the implementation rather than guesswork.
- Explain the difference between manually installed standard skills under ~/.agents/skills and skills supplied by an installed extension.
- State where DS4Server stores installed extensions and registry data under its Application Support directory.
A2UI interactive surfaces
- Explain that A2UI is generated by the agent when an interactive or graphical response is useful; it is not a separate model or a tool the user manually operates.
- Explain how to enable/disable A2UI in Preferences, ask for an interactive surface, switch to the A2UI view, interact with controls, navigate saved surface history, and dismiss a surface.
- List the components currently supported by the embedded A2UI catalog, using assets/a2ui/catalog.json as the source of truth:
  - content: Markdown/text, images/avatars, icons, video, audio, and dividers;
  - layout: rows, columns, lists, cards, modals, and tabs;
  - controls: buttons, text fields, checkboxes, sliders, date/time inputs, and choice pickers;
  - visual/research components: bar, line, area, stacked-bar, pie, donut, and heatmap charts, tables, metrics, timelines, maps, mind maps, and forms.
- Explain that media opens in native playback windows and that ordinary prose remains in the Chat transcript.
- Do not expose protocol JSON or developer validation commands in the new-user flow.
The rest of the app
- Model Manager and the per-model/per-thinking settings.
- Chat, A2UI, Git, and Stats views.
- Sidebar and branch controls.
- Git staging, diff, commit, fetch, pull, and push behavior.
- Local OpenAI-/Anthropic-compatible endpoint and its local-only/CORS defaults.
- Data locations, deletion consequences, and recovery behavior.
- A concise troubleshooting section for common first-run problems such as no model selected, model verification failure, context rebuilds, extension manifest/hook errors, and denied tool approval.
Keyboard shortcuts
- Add one compact table containing all shortcuts actually registered in src/native_menu.rs, including F1 — DS4Server User Guide.
- Remove stale shortcuts whenever the native menu changes.

The guide must describe current, shipped behavior only. Cross-check claims against the UI, configuration defaults, extension implementation, A2UI catalog, and native menus; do not copy developer-oriented README instructions into the user guide without translating them for end users.

Tests and verification

Add a focused regression check for the Help menu accelerator showing that the User Guide is assigned Code::F1 with no modifiers.
Ensure the embedded docs/USER_GUIDE.md still parses and renders through the existing Markdown help view.
Manually verify in the bundled macOS app:
1. Help > DS4Server User Guide displays F1.
2. Pressing F1 opens the guide.
3. Pressing it again focuses the existing guide window and does not create another.
4. The guide scrolls from the getting-started section through all sections above without clipped content.
5. Extension and A2UI instructions match the current Preferences UI and actual behavior.
Run the repository commit gates.

Acceptance criteria

The native Help menu and F1 both open/focus the same User Guide window.
The obsolete ⇧⌘/ Help shortcut is removed.
A fresh user can use the guide alone to understand initial setup, the main views, agent/tool safety, extensions, A2UI capabilities, models, Git, Dev Brain/Ralph/skills, the local endpoint, data/recovery, and registered shortcuts.
Extension instructions accurately cover install, optional ref, trust, enable/disable, update, uninstall, errors, storage, and lifecycle behavior.
The documented A2UI component inventory matches the embedded catalog.
No unimplemented or planned feature is presented as available.

## Bug The Help menu's bundled user guide is not discoverable through the standard **F1** help shortcut, and the guide no longer describes the capabilities visible in the current app. Current behavior: - **Help > DS4Server Help** uses `⇧⌘/` in `src/native_menu.rs`. - `docs/USER_GUIDE.md` is embedded into the app and shown in the help window. - The guide incorrectly says that there is no built-in extension installer, while **Preferences > Agent Extensions** can already install portable Codex plugins from HTTPS Git repositories and manage them. - A2UI is only mentioned at a high level, without explaining its available components or how users ask for and interact with a surface. - Important capabilities are scattered through the guide rather than presented as an onboarding path a new user can read from start to finish. This leaves new users without a reliable overview of what DS4Server can do or how to access it. ## Required fix ### 1. Use F1 for the User Guide - Rename the Help menu entry to **DS4Server User Guide**. - Replace the current `⇧⌘/` accelerator with unmodified **F1** using the native menu accelerator. - F1 and the menu item must use the existing `OpenHelp` path: open one help window, or focus the existing help window instead of creating duplicates. - Do not add a global event monitor or custom key listener. The native menu accelerator is the source of truth. - On Macs whose system settings map the top row to media/brightness controls, the user may need to press `fn-F1`; DS4Server must not override the system mapping. - Update every shortcut reference in the bundled guide so the displayed documentation and native menu agree. ### 2. Turn the bundled help into a complete user guide Rewrite and expand `docs/USER_GUIDE.md` as user-facing documentation for the shipped application. Keep it readable in the existing scrollable Markdown help window; no help-window redesign is required. Organize it so a fresh user can follow it in order: 1. **Getting started** - Install or select a supported model in Model Manager. - Add a project. - Start a chat, choose a thinking profile and permission mode, and send the first prompt. - Explain that models, chats, project references, configuration, and extension data stay local. 2. **Projects, chats, and context** - Creating, switching, renaming, pinning, archiving, deleting, exporting, stopping, and queuing prompts. - Concurrent chats and the single shared model runtime. - Context usage, compaction, checkpoints, and context rebuilds after model/runtime changes. 3. **Agent capabilities and safety** - Explain, in user language, the available categories: file listing/reading/searching, writing/editing, shell commands, web search/page visits, Git work, approvals, Ralph loops, workspace instructions, standard skills, and Dev Brain. - Clearly distinguish content search, filename discovery once the native glob tool is available, and shell execution. Do not document issue #82 as shipped until it is actually implemented. - Explain permission modes, what triggers approval, cancellation, structured tool errors, and saved large tool output. 4. **Agent extensions** - Replace the obsolete statement that no installer exists. - Document **Preferences > Agent Extensions** and the complete current workflow: - install from an HTTPS Git repository; - optionally pin a branch, tag, or commit; - the repository must be a portable Codex plugin with `.codex-plugin/plugin.json` and at least skills or supported lifecycle hooks; - inspect the displayed source, resolved commit, author, version, skill count, and hooks; - enable/disable, manually update, and uninstall; - command hooks require an explicit trust confirmation and run with the user's permissions despite DS4Server's environment, timeout, and output limits; - hook failures are shown on the extension; - explain when changes affect the current chat versus when a fresh chat/restart is needed, based on the implementation rather than guesswork. - Explain the difference between manually installed standard skills under `~/.agents/skills` and skills supplied by an installed extension. - State where DS4Server stores installed extensions and registry data under its Application Support directory. 5. **A2UI interactive surfaces** - Explain that A2UI is generated by the agent when an interactive or graphical response is useful; it is not a separate model or a tool the user manually operates. - Explain how to enable/disable A2UI in Preferences, ask for an interactive surface, switch to the A2UI view, interact with controls, navigate saved surface history, and dismiss a surface. - List the components currently supported by the embedded A2UI catalog, using `assets/a2ui/catalog.json` as the source of truth: - content: Markdown/text, images/avatars, icons, video, audio, and dividers; - layout: rows, columns, lists, cards, modals, and tabs; - controls: buttons, text fields, checkboxes, sliders, date/time inputs, and choice pickers; - visual/research components: bar, line, area, stacked-bar, pie, donut, and heatmap charts, tables, metrics, timelines, maps, mind maps, and forms. - Explain that media opens in native playback windows and that ordinary prose remains in the Chat transcript. - Do not expose protocol JSON or developer validation commands in the new-user flow. 6. **The rest of the app** - Model Manager and the per-model/per-thinking settings. - Chat, A2UI, Git, and Stats views. - Sidebar and branch controls. - Git staging, diff, commit, fetch, pull, and push behavior. - Local OpenAI-/Anthropic-compatible endpoint and its local-only/CORS defaults. - Data locations, deletion consequences, and recovery behavior. - A concise troubleshooting section for common first-run problems such as no model selected, model verification failure, context rebuilds, extension manifest/hook errors, and denied tool approval. 7. **Keyboard shortcuts** - Add one compact table containing all shortcuts actually registered in `src/native_menu.rs`, including **F1 — DS4Server User Guide**. - Remove stale shortcuts whenever the native menu changes. The guide must describe current, shipped behavior only. Cross-check claims against the UI, configuration defaults, extension implementation, A2UI catalog, and native menus; do not copy developer-oriented README instructions into the user guide without translating them for end users. ## Tests and verification - Add a focused regression check for the Help menu accelerator showing that the User Guide is assigned `Code::F1` with no modifiers. - Ensure the embedded `docs/USER_GUIDE.md` still parses and renders through the existing Markdown help view. - Manually verify in the bundled macOS app: 1. **Help > DS4Server User Guide** displays **F1**. 2. Pressing F1 opens the guide. 3. Pressing it again focuses the existing guide window and does not create another. 4. The guide scrolls from the getting-started section through all sections above without clipped content. 5. Extension and A2UI instructions match the current Preferences UI and actual behavior. - Run the repository commit gates. ## Acceptance criteria - The native Help menu and F1 both open/focus the same User Guide window. - The obsolete `⇧⌘/` Help shortcut is removed. - A fresh user can use the guide alone to understand initial setup, the main views, agent/tool safety, extensions, A2UI capabilities, models, Git, Dev Brain/Ralph/skills, the local endpoint, data/recovery, and registered shortcuts. - Extension instructions accurately cover install, optional ref, trust, enable/disable, update, uninstall, errors, storage, and lifecycle behavior. - The documented A2UI component inventory matches the embedded catalog. - No unimplemented or planned feature is presented as available.

hugo added the bug label 2026-08-30 20:58:56 +00:00

hugo commented

2026-08-31 05:44:13 +00:00

Implemented and pushed in 7f88e23. The native Help item is now named DS4Server User Guide and uses unmodified F1 through the existing OpenHelp path, which opens one window or focuses the existing one. Rewrote the bundled guide into a complete source-checked onboarding reference covering projects/chats/context, tool safety, Ralph, workspace instructions, skills, Agent Extensions, A2UI catalog components, models, Git, local API, data/recovery, troubleshooting, and every native menu shortcut. Added a focused regression test for Code::F1 with no modifiers. Verification: cargo fmt --all -- --check; cargo clippy --all-targets --all-features -- -D warnings; make bundle; cargo test --all-features (208 passed, 17 ignored hardware/browser fixtures). Bundled-app verification confirmed the menu label, F1 open/focus behavior, no duplicate help window, and scrolling through the full Markdown guide. DS4 has no corresponding native macOS help UI; this is DS4Server-specific.

Implemented and pushed in 7f88e23. The native Help item is now named DS4Server User Guide and uses unmodified F1 through the existing OpenHelp path, which opens one window or focuses the existing one. Rewrote the bundled guide into a complete source-checked onboarding reference covering projects/chats/context, tool safety, Ralph, workspace instructions, skills, Agent Extensions, A2UI catalog components, models, Git, local API, data/recovery, troubleshooting, and every native menu shortcut. Added a focused regression test for Code::F1 with no modifiers. Verification: cargo fmt --all -- --check; cargo clippy --all-targets --all-features -- -D warnings; make bundle; cargo test --all-features (208 passed, 17 ignored hardware/browser fixtures). Bundled-app verification confirmed the menu label, F1 open/focus behavior, no duplicate help window, and scrolling through the full Markdown guide. DS4 has no corresponding native macOS help UI; this is DS4Server-specific.

hugo closed this issue

2026-08-31 05:44:17 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/DS4Server#83