Update agent feature documentation

README.md

@@ -15,7 +15,19 @@ the Metal kernels and small native integration layers are adapted from
 - **Local coding tools.** The agent can read, search, list, write, and edit
   project files; run and monitor asynchronous shell commands; search Google;
   and visit rendered web pages. File access is confined to the project, output
-  is bounded, and risky shell or visible-browser actions require approval.
+  is bounded, risky shell or visible-browser actions require approval, and
+  tool calls are validated against the same typed schemas shown to the model.
+- **Fresh-agent Ralph loops.** For a bounded coding objective, the agent can
+  run foreground rounds in fresh model contexts while preserving workspace
+  changes between rounds. A validated structured report is the only
+  conversational handoff to the next worker; the loop stops on reported
+  completion, a blocker, failure, cancellation, or its configurable round
+  limit.
+- **Workspace instructions and reusable skills.** A global `AGENTS.md` plus
+  project and nested `AGENTS.md`/`AGENTS.local.md` files provide hierarchical
+  guidance that is reconciled as the agent enters or changes a workspace area.
+  Standard `~/.agents/skills/<name>/SKILL.md` packages are advertised by
+  metadata and loaded in full only when a task matches.
 - **Project-backed Dev Brain.** An optional managed Obsidian vault provides
   source-verified wiki pages, ranked search, and on-demand skills. Each session
   receives the verified skill names, descriptions, and paths, then loads full
@@ -93,18 +105,24 @@ make bundle
 open target/release/DS4Server.app
 ```
 
+Tagged versions are also published as Apple Silicon DMG files on the
+[repository releases page](https://git.rfc1437.de/hugo/DS4Server/releases).
+
 ## Application data
 
 ```text
 ~/Library/Application Support/de.rfc1437.ds4server/data.sqlite3
 ~/Library/Application Support/de.rfc1437.ds4server/config.yaml
+~/Library/Application Support/de.rfc1437.ds4server/AGENTS.md
 ~/Library/Application Support/de.rfc1437.ds4server/models/
 ~/Library/Application Support/de.rfc1437.ds4server/kv-cache/
 ```
 
 Deleting a project or session removes DS4Server metadata and its associated
-checkpoint; it never deletes the referenced project directory. See
+checkpoint; it never deletes the referenced project directory. Standard agent
-[PLAN.md](PLAN.md) for the remaining implementation work.
+skills live separately under `~/.agents/skills/`. See the
+[issue tracker](https://git.rfc1437.de/hugo/DS4Server/issues) for remaining
+implementation work.
 
 The adapted Metal and browser sources retain their upstream notices in
 [`native/metal/LICENSE`](native/metal/LICENSE) and

docs/USER_GUIDE.md

@@ -92,7 +92,70 @@ 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.
+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