From 7f88e23884cf4374d1c8a2fc7a96a5ea837223e8 Mon Sep 17 00:00:00 2001 From: Georg Bauer Date: Mon, 31 Aug 2026 07:43:29 +0200 Subject: [PATCH] Make F1 open the complete User Guide --- docs/USER_GUIDE.md | 415 +++++++++++++++++++++++++-------------------- src/native_menu.rs | 28 ++- 2 files changed, 249 insertions(+), 194 deletions(-) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index d82cb28..de6a41c 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,230 +1,275 @@ -# DS4Server Help +# DS4Server User Guide -DS4Server runs supported DwarfStar language models locally on your Mac. Chats, -project references, and settings stay on this computer. +DS4Server is a native macOS application for running supported DwarfStar models +locally. Model files, chats, project references, settings, checkpoints, and +agent-extension data stay on this Mac. -## Projects and chats +## Getting started -Choose **Add project** to give the coding agent access to a folder. The agent's -file tools are bounded to that project. Use **File > New Chat** (`⌘N`) to start -a chat in the active project. Chats are saved after their first message and can -be renamed, pinned, archived, compacted, rebuilt, or deleted from the sidebar. -An active chat has a green dot beside its title. You can switch chats or start -another one while it works; each chat keeps its own transcript, queued prompts, -tools, approvals, context, and interactive UI state. Model inference shares the -single loaded runtime so model weights are not duplicated, while independent -tool work continues concurrently. +1. Open **View > Model Manager** (`⇧⌘M`). Download a supported model and any + acceleration artifact you intend to use, or verify an artifact already on + disk. A model cannot run until its complete file passes verification. +2. Choose **Add project** and select the folder the agent should work in. The + project remains in its original location; DS4Server stores only its reference + and chat data. +3. Choose **File > New Chat** (`⌘N`). Select a thinking profile and a shell + permission mode in the composer. +4. Enter a request and send it. **Thinking** is the DS4 default, **Direct** omits + hidden reasoning, and **Think Max** appears only when that model profile has + the required long context. -The composer status row shows the current project and, for Git repositories, -the current local branch. An unsaved draft can be moved with the project menu; -saved chats keep their original project. Use the branch menu to switch local -branches when that project's chats are idle. The thinking menu is preselected -to the active model's default mode and loads that model-and-thinking profile: -**Thinking** is the DS4 default, while **Direct** answers without hidden -reasoning. **Think Max** is available when its profile uses at least 393216 -context tokens, matching DS4's long-context requirement. +The selected model is shared by the app and the optional local HTTP endpoint. +Preferences are saved locally and generation settings are scoped by model and +thinking profile where the controls indicate that. -The **Git** pane shows added, changed, and deleted files from the current -worktree, including separate staged and worktree markers. Select files to stage, -unstage, or commit them, or commit the existing staged set. Committing with no -selection or staged files asks before staging and committing every change. File -names open a colored diff that can switch between unified and side-by-side -layouts. The fetch, pull, and push actions use the `origin` remote and report -authentication, hook, conflict, and other Git errors without hiding them. +## Projects, chats, and context -Quitting with active chats asks for confirmation. Confirming stops their model -and tool work; canceling leaves every chat running. +The sidebar switches projects and chats. Project controls add, rename, or delete +a project reference. Deleting one removes its DS4Server sessions and +checkpoints, but never deletes the referenced folder. An unsaved draft can move +to another project; a saved chat remains attached to its original project. -Use **File > Export Chat as Markdown** (`⇧⌘S`) to save the visible conversation, -including reasoning and tool results. System-only messages are omitted. +Chat controls can rename, pin, archive, restore, compact, rebuild, export, or +delete a conversation. Archived chats remain under the project's archive until +restored or deleted. Deleting a chat permanently removes its transcript and KV +checkpoint. **File > Export Chat as Markdown** (`⇧⌘S`) saves the visible +conversation, including reasoning and tool results but excluding internal +system messages. -## Writing and editing +Send another prompt while a response is active to queue it for that chat. +**Stop** cancels current model and agent work. You can work in several chats at +once: each keeps its own transcript, prompt queue, tools, approvals, context, +and interactive surfaces. Independent tool work may overlap, but model +inference is serialized through one shared runtime so weights are not duplicated. +Quitting with active chats asks whether to stop them first. -Enter a prompt at the bottom of the Chat view. While a response is running, -additional prompts are queued. **Stop** cancels generation and active agent -work. The Edit menu follows the focused text control and supports undo, redo, -cut, copy, paste, and select all. Transcript text can be selected and copied. +The context indicator shows used and available tokens. Near the limit, +DS4Server compacts older model context while retaining the full visible +transcript. Saved chats also keep local KV checkpoints for fast continuation. +A checkpoint belongs to the exact model, quantization, context size, and runtime +configuration that created it. After one of those changes, DS4Server reports a +context rebuild, prefills the saved transcript, and writes a compatible +replacement without losing messages. **Rebuild context on next use** requests +the same safe rebuild manually. -The context indicator beside the composer shows used and available tokens. -DS4Server automatically compacts long chats near the context limit; the full -visible transcript remains available. +## Agent capabilities and safety -## Checkpoints and model changes +The coding agent can use native tools to list a directory, read files, search +file contents, write or edit files, inspect Git state, and maintain Dev Brain. +It can also run shell commands and use web search or visit pages when the task +needs them. Content search is not filename discovery: until DS4Server ships a +native filename glob tool, recursive filename lookup may require an approved +shell command. A directory listing remains a non-recursive view of one folder. -Each saved chat keeps a local KV checkpoint so its next turn can resume without -prefilling the whole conversation. A checkpoint belongs to the exact model, -quantization, context size, and executor configuration that created it. +Tool calls are checked against typed schemas before execution. Unknown tools, +missing or extra fields, malformed calls, and invalid values return structured +errors instead of running. Results appear in the transcript. Copy actions expose +their complete text, and large output may also be saved to a local file rather +than filling the transcript. **Stop** cancels active generation and cancellable +tool work. -If the selected model, model file, quantization, context size, or relevant -runtime configuration changes, DS4Server cannot safely resume that checkpoint. -It reports that the context is being rebuilt, prefills the saved transcript, -and writes a compatible replacement. No chat messages are lost. **Rebuild -context on next use** performs the same safe rebuild manually. +The shell permission mode is stored with each chat: -## Models +- **Heuristic** applies DS4Server's built-in command-risk checks. +- **AI based** asks the local model to classify a shell command in a separate + one-shot request. A risky result shows its reason. If classification fails or + is invalid, approval is required. -Open **View > Model Manager** (`⇧⌘M`) to download, resume, verify, or remove -supported model artifacts. Preferences choose the active model and control -generation, context, speculative decoding, Metal execution, SSD expert -streaming, steering, checkpoint storage, diagnostics, and the local endpoint. -Generation values are stored per model and thinking mode. Acceleration and SSD -values are stored per model, while the Prompt section's system prompt is shared -by every profile. +An approval dialog shows the command and working directory. **Allow once** runs +that operation; **Deny** returns the refusal to the agent. Destructive, network, +privileged, application-control, credential, and outside-trusted-path commands +require approval as applicable. Dev Brain's configured vault is trusted like +the project for ordinary path checks, but does not bypass those risk classes. -Model files are large. Verification checks the complete artifact before it is -used. Removing a model never removes projects or chat history. +### Ralph loops -## Agent tools and approvals +Ask the agent to use a Ralph loop when a bounded task benefits from repeated +autonomous passes, for example, “Use a Ralph loop with at most 12 rounds to fix +and verify this parser.” Ralph is an agent tool, not a view or slash command. +Its default is 8 rounds and its allowed range is 1–64. -The local agent can inspect and edit project files, search text, and run shell -commands. Operations that can affect data outside the ordinary project workflow -show an approval dialog. Read the command and working directory before choosing -**Allow once**. Choose **Deny** to return the refusal to the agent. +Each round receives the same objective in a fresh model context, inspects the +current project, and leaves file changes on disk. The next round receives only +the previous validated report, applicable workspace instructions, and available +skills. The current model settings and permission mode still apply. Ralph stops +on completion, a reported blocker, a failed round, cancellation, or the round +limit; a worker's completion report is evidence to review, not independent +certification. Ralph workers cannot start nested Ralph loops. -The permission selector at the bottom of each chat is stored with that session. -**Heuristic** uses the built-in command checks. **AI based** asks the local model -to classify each shell command in an isolated one-shot request; risky commands -show the model's reason in the normal approval dialog. If that check fails or -returns an invalid answer, DS4Server requires approval. Preferences choose the -default for new sessions. When Dev Brain is enabled, its configured vault is -treated like the project for path-risk checks; destructive, network, privilege, -application-control, and credential risks still require approval. +### Workspace instructions and standard skills -Tool calls and results appear in the transcript. Use their copy actions for the -complete, untruncated text; large outputs can also be opened from their saved -file. Calls are checked against typed schemas before execution, so unknown -tools, missing or extra fields, invalid values, and malformed tool syntax are -returned to the agent as structured errors instead of being executed. +DS4Server reads global instructions from +`~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md`, then project +instructions from root to the working directory. In each directory, +`AGENTS.local.md` overlays `AGENTS.md`. Deeper guidance wins over broader +guidance, while system, developer, and direct user instructions remain higher +priority. Additions, changes, and removals are tracked during a chat and restored +after compaction; an unreadable changed file leaves its last readable version in +effect with a notice. -## Ralph loops +Manually installed standard skills live at +`~/.agents/skills//SKILL.md`. DS4Server initially gives the agent each +valid skill's name, description, and location; the agent reads the full skill +only when the task matches. These roots are readable but not writable through +agent file tools. Start a fresh chat after changing the manually installed skill +set so its prompt and tool roots agree. -For a bounded task that benefits from repeated autonomous passes, ask the agent -to use a Ralph loop, for example: “Use a Ralph loop with at most 12 rounds to -fix and verify this parser.” This is an agent tool, not a slash command or a -separate view. The normal default is 8 rounds and the allowed range is 1–64. +### Dev Brain -Ralph runs in the foreground. Each round receives the same immutable objective -in a fresh model context, inspects the current project as its source of truth, -and ends with one structured report. File changes remain on disk between -rounds, but earlier conversation does not: only the previous validated report, -applicable workspace instructions, and available skills are handed to the next -worker. This limits accumulated context while allowing the next round to -continue, verify, or repair the work. +Dev Brain is a project-backed Obsidian wiki for durable, source-cited engineering +knowledge. In **Preferences > Dev Brain**, select an existing vault containing +`.obsidian`, enable it, and save. Ask the agent to build, refresh, search, or +validate the wiki. DS4Server manages its contract files and explicitly marked +topic pages, not Obsidian settings, hidden files, attachments, or unrelated +notes. Verified pages can support answers; stale or needs-review pages are leads +that the agent must recheck against project source. Disabling Dev Brain removes +its tools and guidance without deleting the vault. -The current chat's model settings and permission mode still apply. Risky shell -commands and visible browser actions can therefore pause for the usual -approval. **Stop** cancels the loop and its active work. Ralph also stops when a -worker reports completion or a blocker, a child round fails, or the round limit -is reached. Completion is a worker report rather than independent -certification; review its evidence or ask the parent agent to verify it when -that distinction matters. Ralph workers cannot start nested Ralph loops. +## Agent extensions -## Workspace instructions and standard skills +**Preferences > Agent Extensions** installs and manages portable Codex plugins: -DS4Server applies workspace guidance from these locations: +1. Enter an HTTPS Git repository URL and, optionally, a branch, tag, or commit. +2. Choose **Install**. The repository must contain + `.codex-plugin/plugin.json` and provide at least a skills directory or a + supported lifecycle-hooks manifest. +3. Inspect the displayed description, source URL, requested ref, resolved + commit, author, version, skill count, and hook names. +4. Enable the extension. An extension with command hooks first asks for explicit + trust. Its programs run with your user permissions even though DS4Server + invokes them without a shell and limits their environment, runtime, input, + and output. +5. Use **Update** to fetch the configured source/ref, disable the toggle to stop + future use, or **Uninstall** to remove the installed package and its stored + extension data. Hook failures appear on the extension row. -- `~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md` applies to all - projects. -- `AGENTS.md` in the project root applies to that project. -- `AGENTS.md` and `AGENTS.local.md` in nested directories apply after the agent - successfully reads, writes, or edits a file in that part of the project. +Enable, disable, and update changes apply to subsequent matching hook events. +A current chat does not retroactively receive a `SessionStart` event. Because a +chat's native tool roots are initialized for that session, start a fresh chat +after adding, updating, enabling, or disabling extension skills. An app restart +is not otherwise required. -Instructions are ordered from broad to specific. A deeper file takes -precedence over broader guidance, and `AGENTS.local.md` is the final overlay for -its directory. DS4Server records additions, changes, and removals during an -ongoing chat and restores the applicable instruction set after context -compaction. Files that cannot be read safely produce a context notice; if the -file was already tracked, its last readable version remains in effect. -Workspace instructions cannot override system, developer, or direct user -instructions. +Extension skills are versioned inside their plugin and are managed with its +toggle, update, and uninstall actions. They are separate from manually installed +standard skills under `~/.agents/skills`. Installed packages, per-extension +data, and `registry.json` live under +`~/Library/Application Support/de.rfc1437.ds4server/extensions/`. -Reusable standard skills are discovered from -`~/.agents/skills//SKILL.md`. Each `SKILL.md` starts with YAML frontmatter: +## A2UI interactive surfaces -```yaml ---- -name: review-release -description: Review a release against this project's checklist. ---- -``` +A2UI is an interactive or graphical response the agent can generate when it is +more useful than prose. It is not another model and is not a tool you operate +directly. Enable or disable it in Preferences. Ask for an interactive chart, +table, form, map, or other surface, then open the **A2UI** view (`⌘2`) if the app +does not switch there automatically. -The directory name must match `name`; names use lowercase letters, digits, and -single hyphens. DS4Server initially gives the agent only each valid skill's -name, description, and path. When a task matches, the agent reads the complete -file and any needed resources from that skill directory. Standard skill files -are readable but not writable through agent tools. Install only skills you -trust, place them manually before starting a chat, and start a new chat after -changing the installed set. There is currently no built-in skill installer or -extension marketplace. +Buttons can send events back to the agent. Text fields, checkboxes, sliders, +date/time inputs, and choice pickers update the surface's data. Tabs and modals +organize content. Previous and next actions navigate saved surface history; +**Dismiss** removes the current saved surface after confirmation. Ordinary model +prose remains in the Chat transcript. Video and audio controls open native +playback windows. -## Dev Brain +The embedded catalog currently supports: -Dev Brain is a project-backed wiki for durable engineering knowledge. It lets -the coding agent compile architecture, behavior, decisions, invariants, -workflows, and relationships once, then retrieve that verified context in later -chats. Registered projects remain authoritative; Dev Brain is not a general -memory store and never replaces checking changed source code. +- Content: Markdown/text, images and avatars, icons, video, audio, and dividers. +- Layout: rows, columns, lists, cards, modals, and tabs. +- Controls: buttons, text fields, checkboxes, sliders, date/time inputs, and + single- or multiple-choice pickers. +- Visual and research components: bar, line, area, stacked-bar, pie, donut, and + heatmap charts; tables; metrics; timelines; maps; mind maps; and forms. -To set it up: +## The rest of the app -1. Create or choose a dedicated Obsidian vault. The folder must already contain - **.obsidian**. -2. Open **Preferences > Dev Brain**, choose the vault, enable Dev Brain, and - save. -3. In a project chat, ask the agent to build or refresh Dev Brain. Tell it the - questions and areas that matter most so it can maintain **purpose.md** and - compile a small set of useful topic pages instead of summarizing every file. +### Models and preferences -Useful requests include “Build Dev Brain for these projects,” “Refresh Dev -Brain after my recent changes,” “What does Dev Brain know about the cache -invariants?”, and “Check the wiki, then verify this against the source.” The -agent gets the real vault folder from Dev Brain, then uses its normal list, -read, search, write, and edit tools on the Markdown. A dedicated validation tool -checks the result and refreshes the disposable local SQLite search index. +**Model Manager** downloads, resumes, verifies, and removes managed model and +acceleration artifacts. Removing an artifact does not remove projects or chats. +Preferences select the active model and its default thinking profile. Generation +values are stored per model and thinking mode; acceleration and SSD settings are +stored per model; the custom system prompt is shared across profiles. Other +sections control A2UI, permission defaults, endpoint settings, Git diff display, +Dev Brain, extensions, checkpoint storage, and diagnostics. -The vault remains ordinary Obsidian Markdown: +### Main views, sidebar, and branches -- **purpose.md** records its scope, priorities, and recurring questions. -- **schema.md** is the detailed contract the agent follows when maintaining it. -- **index.md** is a generated catalog of every managed topic page. -- **log.md** is an append-only history of material updates. -- Topic pages live under **projects/**, **subsystems/**, **concepts/**, - **decisions/**, **invariants/**, and **workflows/** as needed. +**Chat** shows the conversation, **A2UI** shows interactive surfaces, **Git** +shows the current worktree, and **Stats** reports model, generation, HTTP, SSD, +and KV-cache activity. **View > Show Sidebar** (`⌘B`) hides or restores the +project sidebar. The composer status shows the active project and its local Git +branch. Branch switching is available while that project's chats are idle. -Every topic cites exact project files and a Git revision or content hash. -**Verified** pages may support answers. **Stale** pages are navigation leads -whose evidence changed, and **needs-review** pages contain visible uncertainty; -the agent must recheck project sources before relying on either. After editing, -the agent runs validation. Unsafe paths and invalid page structure or provenance -are errors to repair in place. Broken links are reported as warnings: the valid -page stays on disk, so the agent can make a small edit or create the missing -page without regenerating its work. Validation rebuilds **index.md** -deterministically instead of asking the model to keep it synchronized. +### Git -DS4Server may modify only the four contract files and topic pages explicitly -marked as Dev Brain-managed. Standard agent file tools can access the vault but -cannot modify Obsidian settings, hidden files, or unrelated notes. You can -inspect, edit, link, and version the managed Markdown normally; invalid manual -edits are reported rather than silently trusted. Disabling Dev Brain removes its -folder, search, and validation guidance from the built-in coding agent without -deleting the vault. +The Git view separates staged and worktree changes. Select files to stage, +unstage, or commit; selecting a file opens a colored unified or side-by-side +diff. Committing with no selected or staged files asks before staging and +committing every change. Fetch, pull, and push use the `origin` remote and report +authentication, hook, conflict, and other Git errors. -## Views and sidebar - -Use **View > Show Sidebar** (`⌘B`) to hide or restore the project sidebar. The -Chat view shows the transcript, A2UI shows the latest interactive surface, and -Stats reports model, generation, HTTP, SSD, and KV-cache activity. - -## Local HTTP endpoint +### Local API Preferences can enable an OpenAI- and Anthropic-compatible endpoint on -`127.0.0.1` (port `4000` by default). Endpoint conversations are owned by their -client and do not appear in the project sidebar. CORS is off by default and -should only be enabled for trusted local browser clients. +`127.0.0.1`, port `4000` by default. Endpoint conversations belong to their +client and do not appear in the sidebar. CORS is off by default; enable it only +for trusted browser clients on this Mac. Saving changed endpoint settings +restarts the local listener. -## Data and recovery +### Data and recovery -Application data is stored under `~/Library/Application Support/de.rfc1437.ds4server/`. -Deleting a project from DS4Server removes its saved sessions and checkpoints, -but never deletes the referenced project folder. Deleting a session removes its -transcript and checkpoint permanently. +Application data is under +`~/Library/Application Support/de.rfc1437.ds4server/`: `config.yaml` stores +preferences, `data.sqlite3` stores projects and chats, `models/` stores managed +artifacts, `kv-cache/` stores checkpoints and metrics data, `extensions/` stores +plugins, and `browser/` stores the agent browser profile. Project source remains +where you selected it. + +Removing a model can be recovered by downloading or restoring and verifying the +same artifact. A context incompatible with changed runtime settings is rebuilt +from the saved transcript. Deleted project references, chats, extension data, +and their checkpoints are not restored by DS4Server; use your own backup if you +need recovery from deletion. + +## Troubleshooting + +- **No model selected or model unavailable:** select a model in Preferences, + then download and verify all required artifacts in Model Manager. +- **Verification failed:** retry verification or download. DS4Server will not + load incomplete or hash-mismatched weights. +- **Context is rebuilding:** the saved checkpoint no longer matches current + model/runtime settings. Let the transcript prefill finish; messages remain. +- **Extension install failed:** use an HTTPS Git URL and verify the repository + contains a valid portable plugin manifest plus skills or supported hooks. +- **Extension hook failed:** read the error on its Preferences row, repair or + update the extension, then retry the matching event. Trust is required before + command hooks can run. +- **Tool approval denied:** the operation was not run. Send a safer request or + repeat it and approve only after checking the command and working directory. +- **A2UI is unavailable:** enable A2UI in Preferences and ask the agent for an + interactive surface in a new prompt. + +## Keyboard shortcuts + +These are the shortcuts registered by the native DS4Server menu. On Macs whose +top row controls brightness or media, use `fn-F1` when macOS requires it; +DS4Server does not override the system keyboard mapping. + +| Shortcut | Action | +| --- | --- | +| `F1` | DS4Server User Guide | +| `⌘,` | Preferences | +| `⇧⌘M` | Model Manager | +| `⌘N` | New Chat | +| `⇧⌘S` | Export Chat as Markdown | +| `⌘B` | Show or hide the sidebar | +| `⌘1` | Chat view | +| `⌘2` | A2UI view | +| `⌘3` | Git view | +| `⌘4` | Stats view | +| `⌘Z` | Undo | +| `⇧⌘Z` | Redo | +| `⌘X` | Cut | +| `⌘C` | Copy | +| `⌘V` | Paste | +| `⌘A` | Select All | +| `⌘Q` | Quit DS4Server | diff --git a/src/native_menu.rs b/src/native_menu.rs index 8d4d38b..7ddf468 100644 --- a/src/native_menu.rs +++ b/src/native_menu.rs @@ -104,15 +104,7 @@ pub(crate) fn install() -> Result { let a2ui = view_item(SHOW_A2UI, "A2UI", Code::Digit2, false); let git = view_item(SHOW_GIT, "Git", Code::Digit3, false); let stats = view_item(SHOW_STATS, "Stats", Code::Digit4, false); - let open_help = MenuItem::with_id( - HELP, - "DS4Server Help", - true, - Some(Accelerator::new( - Some(Modifiers::SUPER | Modifiers::SHIFT), - Code::Slash, - )), - ); + let open_help = help_item(); let undo = edit_item(UNDO, "Undo", Code::KeyZ, None); let redo = edit_item(REDO, "Redo", Code::KeyZ, Some(Modifiers::SHIFT)); let cut = edit_item(CUT, "Cut", Code::KeyX, None); @@ -279,6 +271,14 @@ fn edit_item( ) } +fn help_item() -> MenuItem { + MenuItem::with_id(HELP, "DS4Server User Guide", true, Some(help_accelerator())) +} + +fn help_accelerator() -> Accelerator { + Accelerator::new(None, Code::F1) +} + #[cfg(test)] mod tests { use super::*; @@ -299,4 +299,14 @@ mod tests { assert_eq!(stats.id().0, SHOW_STATS); assert!(!stats.is_checked()); } + + #[test] + fn user_guide_uses_unmodified_f1() { + let accelerator = help_accelerator(); + let item = help_item(); + + assert_eq!(item.text(), "DS4Server User Guide"); + assert_eq!(accelerator.key(), Code::F1); + assert!(accelerator.modifiers().is_empty()); + } }