# DS4Server Help

DS4Server runs supported DwarfStar language models locally on your Mac. Chats,
project references, and settings stay on this computer.

## Projects and chats

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.

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

Quitting with active chats asks for confirmation. Confirming stops their model
and tool work; canceling leaves every chat running.

Use **File > Export Chat as Markdown** (`⇧⌘S`) to save the visible conversation,
including reasoning and tool results. System-only messages are omitted.

## Writing and editing

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 beside the composer shows used and available tokens.
DS4Server automatically compacts long chats near the context limit; the full
visible transcript remains available.

## Checkpoints and model changes

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.

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.

## Models

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.

Model files are large. Verification checks the complete artifact before it is
used. Removing a model never removes projects or chat history.

## Agent tools and approvals

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.

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.

## Dev Brain

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.

To set it up:

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.

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.

The vault remains ordinary Obsidian Markdown:

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

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.

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.

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

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.

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