DS4Server/docs/USER_GUIDE.md

# DS4Server User Guide

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.

## Getting started

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 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.

## Projects, chats, and context

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.

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.

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.

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.

## Agent capabilities and safety

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. The native glob tool finds files recursively by basename or relative
path pattern without a shell; content matching remains the search tool's job,
and a directory listing remains a non-recursive view of one folder.

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.

The shell permission mode is stored with each chat:

- **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.

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.

### Ralph loops

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.

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.

### Workspace instructions and standard skills

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.

Manually installed standard skills live at
`~/.agents/skills/<name>/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.

### Dev Brain

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.

## Agent extensions

**Preferences > Agent Extensions** installs and manages portable Codex plugins:

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.

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.

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/`.

## A2UI interactive surfaces

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.

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.

The embedded catalog currently supports:

- 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.

## The rest of the app

### Models and preferences

**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.

### Main views, sidebar, and branches

**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.

### Git

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.

### Local API

Preferences can enable an OpenAI- and Anthropic-compatible endpoint on
`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

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 |