DS4Server/docs/USER_GUIDE.md

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

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.

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.

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.

## Ralph loops

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.

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.

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.

## Workspace instructions and standard skills

DS4Server applies workspace guidance from these locations:

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

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.

Reusable standard skills are discovered from
`~/.agents/skills/<name>/SKILL.md`. Each `SKILL.md` starts with YAML frontmatter:

```yaml
---
name: review-release
description: Review a release against this project's checklist.
---
```

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.

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