fix: expand reply cwd (~) and document AGENTS

docs/AGENTS.default.md

@@ -6,6 +6,37 @@ read_when:
 ---
 # AGENTS.md — Clawdis Personal Assistant (default)
 
+## First run (recommended)
+
+1) Create a dedicated workspace for your assistant (where it can read/write files):
+
+```bash
+mkdir -p ~/clawd
+```
+
+2) Copy this template to your workspace root as `AGENTS.md`:
+
+```bash
+cp docs/AGENTS.default.md ~/clawd/AGENTS.md
+```
+
+3) Point CLAWDIS at that workspace so Pi runs with the right context:
+
+```json5
+{
+  inbound: {
+    reply: {
+      cwd: "~/clawd"
+    }
+  }
+}
+```
+
+## Safety defaults
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
 ## What Clawdis Does
 - Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run tools via the host Mac.
 - macOS app manages permissions (screen recording, notifications, microphone) and exposes a CLI helper `clawdis-mac` for scripts.

docs/agents.md

@@ -17,6 +17,8 @@ If you don’t configure `inbound.reply`, CLAWDIS uses the bundled Pi binary in
 
 This is usually enough for a personal assistant setup; add `inbound.allowFrom` to restrict who can trigger it.
 
+If you keep an `AGENTS.md` (and optional “memory” files) for the agent, set `inbound.reply.cwd` to that workspace so Pi runs with the right context.
+
 ## Custom agent command (still Pi)
 
 To override the agent command, configure `inbound.reply.mode: "command"`:

docs/clawd.md

@@ -88,6 +88,29 @@ clawdis webchat
 
 Now message the assistant number from your allowlisted phone.
 
+## Give the agent a workspace (AGENTS.md)
+
+Pi (the bundled coding agent) will read operating instructions and “memory” from the current working directory. For a good first-run experience, create a dedicated workspace and drop an `AGENTS.md` there.
+
+From the CLAWDIS repo:
+
+```bash
+mkdir -p ~/clawd
+cp docs/AGENTS.default.md ~/clawd/AGENTS.md
+```
+
+Then set `inbound.reply.cwd` to that directory (supports `~`):
+
+```json5
+{
+  inbound: {
+    reply: {
+      cwd: "~/clawd"
+    }
+  }
+}
+```
+
 ## The config that turns it into “an assistant”
 
 CLAWDIS defaults to a good Pi setup even without `inbound.reply`, but you’ll usually want to tune:
@@ -110,6 +133,8 @@ Example:
       mode: "command",
       // Pi is bundled; CLAWDIS forces --mode rpc for Pi runs.
       command: ["pi", "--mode", "rpc", "{{BodyStripped}}"],
+      // Run the agent from your dedicated workspace (AGENTS.md, memory files, etc).
+      cwd: "~/clawd",
       timeoutSeconds: 1800,
       bodyPrefix: "/think:high ",
       session: {

docs/configuration.md

@@ -81,6 +81,9 @@ Example command-mode config:
       mode: "command",
       // Example: run the bundled agent (Pi) in RPC mode
       command: ["pi", "--mode", "rpc", "{{BodyStripped}}"],
+      // Optional: run the agent from a specific working directory (supports ~).
+      // Useful when you keep an AGENTS.md + memory files in a dedicated workspace.
+      cwd: "~/clawd",
       timeoutSeconds: 1800,
       heartbeatMinutes: 30,
       // Optional: override the command used for heartbeat runs
@@ -103,6 +106,10 @@ Example command-mode config:
 }
 ```
 
+Notes:
+- `inbound.reply.cwd` sets the working directory for the reply command (and Pi RPC). It supports `~` and is resolved to an absolute path.
+- If you don’t set it, the agent runs from the Gateway’s current directory (often not what you want for a “personal assistant” workspace).
+
 ### `browser` (clawd-managed Chrome)
 
 Clawdis can start a **dedicated, isolated** Chrome/Chromium instance for clawd and expose a small loopback control server.

docs/index.md

@@ -116,6 +116,7 @@ Example:
 - Start here:
   - [Configuration](./configuration.md)
   - [Clawd personal assistant setup](./clawd.md)
+  - [AGENTS.md template (default)](./AGENTS.default.md)
   - [Gateway runbook](./gateway.md)
   - [Discovery + transports](./discovery.md)
   - [Remote access](./remote.md)