clearclaw 0.7.0 → 0.8.0

package/dist/plan-usage.d.ts

@@ -0,0 +1,6 @@
+import type { EngineEvent, PlanUsageState } from "./types.js";
+/** Latest normalized readings shared by workspaces on the same engine/account. */
+export declare function recordPlanUsage(state: PlanUsageState, event: Extract<EngineEvent, {
+    type: "plan_usage";
+}>): void;
+export declare function formatPlanUsage(state?: PlanUsageState, maxLength?: number): string;

package/dist/plan-usage.js

@@ -0,0 +1,31 @@
+/** Latest normalized readings shared by workspaces on the same engine/account. */
+export function recordPlanUsage(state, event) {
+    for (const window of event.windows)
+        state.windows.set(window.id, window);
+    if (event.isUsingOverage !== undefined)
+        state.isUsingOverage = event.isUsingOverage;
+}
+export function formatPlanUsage(state, maxLength = 4096) {
+    // A window with nothing to report is omitted: "5h ?" tells the reader less than
+    // its absence does, and the seeded windows start out unreported.
+    const parts = [];
+    for (const window of state?.windows.values() ?? []) {
+        if (window.usedPercent !== undefined)
+            parts.push(`${window.label} ${Math.round(window.usedPercent)}%`);
+        else if (window.limited)
+            parts.push(`${window.label} limited`);
+    }
+    if (state?.isUsingOverage)
+        parts.push("overage");
+    const kept = [];
+    for (const part of parts) {
+        const remaining = parts.length - kept.length - 1;
+        const candidate = [...kept, part].join(", ") + (remaining ? ` +${remaining} more` : "");
+        if (candidate.length > maxLength)
+            break;
+        kept.push(part);
+    }
+    const omitted = parts.length - kept.length;
+    return kept.join(", ") + (omitted ? `${kept.length ? " " : ""}+${omitted} more` : "");
+}
+//# sourceMappingURL=plan-usage.js.map

package/dist/prompt.d.ts

@@ -1,6 +1,10 @@
 /**
  * Assemble the system prompt from framework and user instruction files.
  * Framework content comes first, user content appended after.
- * Returns undefined if no content found in either directory.
+ * `prompt` is undefined if no content was found in either directory;
+ * `skipped` names files that existed but could not be read.
  */
-export declare function assemblePrompt(frameworkDir: string, instructionsDir: string): string | undefined;
+export declare function assemblePrompt(frameworkDir: string, instructionsDir: string): Promise<{
+    prompt: string | undefined;
+    skipped: string[];
+}>;

package/dist/prompt.js

@@ -1,35 +1,78 @@
 import fs from "node:fs";
+import fsp from "node:fs/promises";
 import path from "node:path";
+import log from "./logger.js";
+// A cloud-synced instructions dir (OneDrive/iCloud "dataless" placeholder) can
+// block a read indefinitely. Reading it synchronously froze the whole relay.
+const READ_TIMEOUT_MS = 5000;
+/** Read a file, giving up after READ_TIMEOUT_MS. Returns null on timeout or error. */
+async function readFileOrSkip(file) {
+    // ponytail: Promise.race, not AbortSignal — an abort can't interrupt a read
+    // already blocked in libuv's threadpool, which is exactly what a
+    // cloud-placeholder file does.
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), READ_TIMEOUT_MS);
+    });
+    try {
+        const content = await Promise.race([fsp.readFile(file, "utf-8"), timeout]);
+        if (content === null) {
+            log.warn("[prompt] timed out reading %s after %dms — skipping", file, READ_TIMEOUT_MS);
+            return null;
+        }
+        return content.trim();
+    }
+    catch (err) {
+        log.warn({ err }, "[prompt] could not read %s — skipping", file);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /**
  * Read all .md files from a directory, sorted alphabetically.
- * Returns empty array if directory doesn't exist.
+ * Unreadable files are reported by name instead of silently dropped.
  */
-function readMarkdownFiles(dir) {
+async function readMarkdownFiles(dir) {
     if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir)
-        .filter((f) => f.endsWith(".md"))
-        .sort()
-        .map((f) => fs.readFileSync(path.join(dir, f), "utf-8").trim())
-        .filter(Boolean);
+        return { contents: [], skipped: [] };
+    let entries;
+    try {
+        entries = await fsp.readdir(dir);
+    }
+    catch (err) {
+        // Cloud-synced dirs (Google Drive File Provider) can transiently refuse a listing with EPERM.
+        log.warn({ err }, "[prompt] could not list %s — skipping", dir);
+        return { contents: [], skipped: [dir] };
+    }
+    const names = entries.filter((f) => f.endsWith(".md")).sort();
+    const results = await Promise.all(names.map(async (f) => ({ name: f, text: await readFileOrSkip(path.join(dir, f)) })));
+    return {
+        contents: results.map((r) => r.text).filter((text) => Boolean(text)),
+        skipped: results.filter((r) => r.text === null).map((r) => r.name),
+    };
 }
 /**
  * Assemble the system prompt from framework and user instruction files.
  * Framework content comes first, user content appended after.
- * Returns undefined if no content found in either directory.
+ * `prompt` is undefined if no content was found in either directory;
+ * `skipped` names files that existed but could not be read.
  */
-export function assemblePrompt(frameworkDir, instructionsDir) {
-    const framework = readMarkdownFiles(frameworkDir);
-    const user = readMarkdownFiles(instructionsDir);
-    if (framework.length === 0 && user.length === 0)
-        return undefined;
+export async function assemblePrompt(frameworkDir, instructionsDir) {
+    const framework = await readMarkdownFiles(frameworkDir);
+    const user = await readMarkdownFiles(instructionsDir);
+    const skipped = [...framework.skipped, ...user.skipped];
+    if (framework.contents.length === 0 && user.contents.length === 0) {
+        return { prompt: undefined, skipped };
+    }
     const parts = [];
-    if (framework.length > 0) {
-        parts.push(framework.join("\n\n---\n\n"));
+    if (framework.contents.length > 0) {
+        parts.push(framework.contents.join("\n\n---\n\n"));
     }
-    if (user.length > 0) {
-        parts.push(user.join("\n\n---\n\n"));
+    if (user.contents.length > 0) {
+        parts.push(user.contents.join("\n\n---\n\n"));
     }
-    return parts.join("\n\n");
+    return { prompt: parts.join("\n\n"), skipped };
 }
 //# sourceMappingURL=prompt.js.map

package/dist/scheduler.d.ts

@@ -0,0 +1,15 @@
+import type { Config, ScheduleEntry } from "./config.js";
+import type { InboundMessage } from "./types.js";
+export declare class Scheduler {
+    private config;
+    private inject;
+    private jobs;
+    constructor(config: Config, inject: (msg: Pick<InboundMessage, "origin" | "text">) => void);
+    start(): void;
+    stop(): void;
+    add(entry: ScheduleEntry): void;
+    remove(id: string): void;
+    toggle(id: string, enabled: boolean): void;
+    list(): ScheduleEntry[];
+    private createJob;
+}

package/dist/scheduler.js

@@ -0,0 +1,82 @@
+import { Cron } from "croner";
+import log from "./logger.js";
+export class Scheduler {
+    config;
+    inject;
+    jobs = new Map();
+    constructor(config, inject) {
+        this.config = config;
+        this.inject = inject;
+    }
+    start() {
+        const schedules = this.config.listSchedules();
+        let started = 0;
+        for (const entry of schedules) {
+            if (entry.enabled) {
+                this.createJob(entry);
+                started++;
+            }
+        }
+        if (started > 0) {
+            log.info("[scheduler] started %d schedule(s)", started);
+        }
+    }
+    stop() {
+        for (const [id, job] of this.jobs) {
+            job.stop();
+            log.info("[scheduler] stopped job %s", id);
+        }
+        this.jobs.clear();
+    }
+    add(entry) {
+        this.config.addSchedule(entry);
+        if (entry.enabled) {
+            this.createJob(entry);
+        }
+        log.info("[scheduler] added %s: %s → %s", entry.id, entry.cron, entry.prompt.slice(0, 60));
+    }
+    remove(id) {
+        const job = this.jobs.get(id);
+        if (job) {
+            job.stop();
+            this.jobs.delete(id);
+        }
+        this.config.removeSchedule(id);
+        log.info("[scheduler] removed %s", id);
+    }
+    toggle(id, enabled) {
+        this.config.updateSchedule(id, { enabled });
+        if (enabled) {
+            const entry = this.config.listSchedules().find((s) => s.id === id);
+            if (entry && !this.jobs.has(id)) {
+                this.createJob(entry);
+            }
+        }
+        else {
+            const job = this.jobs.get(id);
+            if (job) {
+                job.stop();
+                this.jobs.delete(id);
+            }
+        }
+        log.info("[scheduler] %s → %s", id, enabled ? "enabled" : "disabled");
+    }
+    list() {
+        return this.config.listSchedules();
+    }
+    createJob(entry) {
+        const opts = {};
+        if (entry.timezone)
+            opts.timezone = entry.timezone;
+        const job = new Cron(entry.cron, opts, () => {
+            log.info("[scheduler] firing %s: %s", entry.id, entry.prompt.slice(0, 60));
+            this.inject({ origin: { kind: "scheduler", scheduleId: entry.id }, text: entry.prompt });
+            if (!job.nextRun()) {
+                this.remove(entry.id);
+                log.info("[scheduler] one-shot %s auto-deleted", entry.id);
+            }
+        });
+        this.jobs.set(entry.id, job);
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/types.d.ts

@@ -4,9 +4,13 @@ export interface ChannelEvents {
 }
 export interface Channel {
     name: string;
+    /** Character budget for the chat status surface, e.g. Slack channel topic. */
+    statusMaxLength?: number;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
+    /** This user's own top-level DM with the bot — home's only valid chat. */
+    isRootDM(chatId: string, userId: string): boolean;
     sendMessage(chatId: string, text: string, opts?: MessageOpts): Promise<string[]>;
     sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
     editMessage(chatId: string, handle: string, text: string, opts?: MessageOpts): Promise<void>;
@@ -17,6 +21,15 @@ export interface Channel {
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
     sendFile(chatId: string, buffer: Buffer, filename: string, opts?: SendFileOpts): Promise<void>;
     reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void>;
+    /**
+     * Group an existing chat under its Project, creating the grouping if it does not exist yet.
+     * Returns a note when grouping did not happen, so the caller can tell the user.
+     */
+    groupProjectChat?(projectName: string, chatId: string): Promise<string | undefined>;
+    /** Create a peer chat. Returns an opaque chat ID; grouping is a separate step. */
+    createProjectChat?(projectName: string, anchor: string, title: string): Promise<string>;
+    /** Close a workspace's chat and remove its Project grouping, regardless of origin. */
+    closeProjectChat?(chatId: string, projectName?: string): Promise<void>;
     on<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
     off<K extends keyof ChannelEvents>(event: K, listener: (...args: ChannelEvents[K]) => void): this;
     emit<K extends keyof ChannelEvents>(event: K, ...args: ChannelEvents[K]): boolean;
@@ -49,10 +62,24 @@ export interface SessionInfo {
     lastModified: number;
     gitBranch?: string;
 }
+/** Chronological conversation text, excluding tool payloads and internal reasoning. */
+export interface SessionMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface SessionHistoryOpts {
+    sessionId: string;
+    cwd: string;
+    signal?: AbortSignal;
+}
 export interface Engine {
     name: string;
+    /** Known account windows to show as unknown before the first observation. */
+    planUsageWindows?: readonly PlanUsageWindow[];
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
     listSessions(cwd: string): Promise<SessionInfo[]>;
+    /** Read history without submitting a new prompt. Reject on unsupported/failed retrieval. */
+    getSessionMessages(opts: SessionHistoryOpts): Promise<SessionMessage[]>;
 }
 export interface RunTurnOpts {
     sessionId: string | null;
@@ -64,6 +91,7 @@ export interface RunTurnOpts {
     appendSystemPrompt?: string;
     mcpServers?: Record<string, McpServerConfig>;
     signal?: AbortSignal;
+    model?: string;
 }
 interface ToolCallBase {
     toolName: string;
@@ -112,11 +140,24 @@ export interface PermissionResponse {
     updatedInput?: Record<string, unknown>;
 }
 export interface TurnStats {
+    modelLabel?: string;
     model: string | null;
     contextUsed: number;
     contextWindow: number;
     toolCalls: Record<string, number>;
 }
+/** Account quota, distinct from a session's context/token usage. Reset times are Unix seconds. */
+export interface PlanUsageWindow {
+    id: string;
+    label: string;
+    usedPercent?: number;
+    resetsAt?: number;
+    limited?: boolean;
+}
+export interface PlanUsageState {
+    windows: Map<string, PlanUsageWindow>;
+    isUsingOverage?: boolean;
+}
 export type EngineEvent = {
     type: "text";
     text: string;
@@ -131,9 +172,13 @@ export type EngineEvent = {
     toolName: string;
     output: string;
 } | {
-    type: "rate_limit";
-    status: string;
-    resetsAt?: number;
+    type: "plan_usage";
+    windows: PlanUsageWindow[];
+    isUsingOverage?: boolean;
+} | {
+    type: "session";
+    sessionId: string;
+    model?: string;
 } | {
     type: "done";
     sessionId: string;
@@ -142,13 +187,27 @@ export type EngineEvent = {
     type: "error";
     message: string;
 };
+export interface EngineHandoff {
+    engine: string;
+    sessionId: string;
+    cwd: string;
+}
 export interface Workspace {
     name: string;
     cwd: string;
-    chat_id: string;
+    chat_id: string | null;
     current_session_id: string | null;
+    engine_handoff?: EngineHandoff;
     behavior?: "assistant" | "relay";
     engine?: string;
+    model?: string;
+    project?: string;
+    description?: string;
+    spawnedFrom?: string;
+    pending_brief?: {
+        fromWorkspace: string;
+        text: string;
+    };
 }
 export interface UserInfo {
     id: string;
@@ -160,6 +219,8 @@ export interface Attachment {
     buffer: Buffer;
     mimeType: string;
     filename?: string;
+    /** Absolute path where the orchestrator saved this file to disk. */
+    savedAs?: string;
 }
 /** Context from a replied-to / quoted message. */
 export interface ReplyContext {
@@ -169,10 +230,21 @@ export interface ReplyContext {
     mediaType?: string;
 }
 export type ChatType = "dm" | "group";
+/** Where an inbound message came from. */
+export type MessageOrigin = {
+    kind: "user";
+    user: UserInfo;
+} | {
+    kind: "scheduler";
+    scheduleId: string;
+} | {
+    kind: "peer";
+    workspaceName: string;
+};
 export interface InboundMessage {
     chatId: string;
     chatType: ChatType;
-    user: UserInfo;
+    origin: MessageOrigin;
     text: string;
     messageId?: string;
     replyTo?: ReplyContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearclaw",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.",
   "type": "module",
   "license": "MIT",
@@ -27,26 +27,32 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "prompts/**/*.md"
+    "prompts/**/*.md",
+    "scripts/patch-codex-acp.mjs",
+    "patches/**"
   ],
   "scripts": {
     "start": "tsx src/index.ts daemon",
     "dev": "tsx --watch src/index.ts daemon",
     "dev:relay": "nodemon --watch dist --exec 'node dist/index.js daemon'",
     "build": "tsc",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "postinstall": "node scripts/patch-codex-acp.mjs"
   },
   "dependencies": {
+    "@agentclientprotocol/codex-acp": "1.11.0",
     "@agentclientprotocol/sdk": "^0.16.1",
     "@anthropic-ai/claude-agent-sdk": "^0.2.89",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@slack/bolt": "^4.6.0",
+    "croner": "^10.0.1",
     "diff": "^8.0.3",
     "grammy": "^1.30.0",
     "mime": "^4.1.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "pino-roll": "^4.0.0",
-    "slackify-markdown": "^5.0.0",
     "telegramify-markdown": "^1.3.3"
   },
   "devDependencies": {
@@ -54,6 +60,7 @@
     "@types/diff": "^7.0.2",
     "@types/node": "^22.0.0",
     "nodemon": "^3.1.14",
+    "telegram": "^2.26.22",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }

package/patches/README.md

@@ -0,0 +1,13 @@
+# Codex ACP usage metadata backport
+
+ClearClaw temporarily pins `@agentclientprotocol/codex-acp` to npm version `1.11.0` and backports the usage notification changes from [codex-acp PR #334](https://github.com/agentclientprotocol/codex-acp/pull/334), head [`b670a4e4914fbd5ffe2d008091e64921dc2684d4`](https://github.com/agentclientprotocol/codex-acp/commit/b670a4e4914fbd5ffe2d008091e64921dc2684d4). The upstream adapter and these adapted changes are Apache-2.0 licensed.
+
+The npm release distributes a bundled `dist/index.js`, so the patch targets that bundle. It forwards account limit updates as ACP `usage_update` notifications and includes all cached quota buckets in `_meta["_codex/rateLimits"]` on context usage updates. Notifications retain the upstream requirement that context usage and a positive context window are known. This does not fetch quotas on demand.
+
+Only the emission changes are backported. Version 1.11.0's existing `mergeRateLimitSnapshot` logic remains intact, including preservation of account-level fields on sparse updates.
+
+`scripts/patch-codex-acp.mjs` runs after installation and uses ClearClaw's existing `diff` dependency. It resolves the installed adapter, checks its exact version and original SHA-256 hash, applies this patch, and verifies the resulting hash. An already patched bundle is accepted, making repeat installation idempotent. Unexpected source fails installation instead of silently dropping quota data.
+
+The installer modifies the resolved dependency in place. In an installation where npm hoists and shares that exact adapter version, other consumers also receive these additive usage metadata notifications. Both the script and patch are included in ClearClaw's published package. Installations using `--ignore-scripts` must explicitly run `node scripts/patch-codex-acp.mjs` from the ClearClaw package directory before relying on Codex quota reporting.
+
+Remove the installer and patch when an upstream release includes this metadata contract, then update the pinned dependency and verify usage notifications.

package/patches/codex-acp-1.11.0.patch

@@ -0,0 +1,38 @@
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -24471,7 +24471,7 @@
+         return this.createMcpToolProgressEvent(notification.params);
+       case "account/rateLimits/updated":
+         this.handleRateLimitsUpdated(notification.params);
+-        return null;
++        return this.createUsageUpdateFromState();
+       case "account/updated":
+         this.onAccountUpdated?.(notification.params);
+         return null;
+@@ -25155,6 +25155,9 @@
+   }
+   createUsageUpdate(params) {
+     this.handleTokenUsageUpdated(params);
++    return this.createUsageUpdateFromState();
++  }
++  createUsageUpdateFromState() {
+     const used = this.sessionState.lastTokenUsage?.totalTokens;
+     const size = this.sessionState.modelContextWindow;
+     if (used == null || size == null || size <= 0) {
+@@ -25163,7 +25166,15 @@
+     return {
+       sessionUpdate: "usage_update",
+       used,
+-      size
++      size,
++      ...this.sessionState.rateLimits ? {
++        _meta: {
++          "_codex/rateLimits": Array.from(this.sessionState.rateLimits.values(), (entry) => ({
++            ...entry.snapshot,
++            limitId: entry.limitId
++          }))
++        }
++      } : {}
+     };
+   }
+   handleRateLimitsUpdated(params) {

package/prompts/SYSTEM.md

@@ -6,16 +6,60 @@ Framework behavior for ClearClaw agents. This file ships with ClearClaw and upda
 
 ## Session Startup
 
-When starting a task session (the system prompt will say so — e.g. workspace onboarding), jump straight into the task. Stay in character, but let the task guide the conversation.
+Before doing anything else — these files live in **ClearClaw home** (`$CLEARCLAW_HOME/workspace`, default `~/.clearclaw/workspace`). From a project cwd, Read them there, not from the project directory.
 
-For regular sessions, before doing anything else:
-
-1. Read `memory/MEMORY.md` — long-term curated memory
-2. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
-3. If a topic comes up that memory mentions, check `knowledge/` before starting from scratch
+1. Read `memory/MEMORY.md` — index with pointers
+2. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent daily logs. If a pointer or topic needs another memory file, Read that `memory/*.md`.
+3. `IDENTITY.md` and `USER.md` are the always-on main identity and user files. Additional role/identity and per-person markdown lives in `instructions/identity/` and `instructions/user/` — Read a file there only when the topic or the speaker needs that extra context.
+4. If a topic comes up that memory mentions, check `knowledge/` before starting from scratch
 
 Don't ask permission. Just do it.
 
+## People
+
+More than one person may talk to you. Each message names its speaker as `[user <id>] Name (@handle)`.
+
+- Identify people by the stable `<id>`, not the display name. Names can collide or change.
+- Don't assume the speaker is the person `USER.md` describes. Check the ID.
+- Keep one person's preferences in `instructions/user/<id>.md` (use the ID with `:` replaced by `-`). Read it when that person speaks and the topic needs it.
+- When a preference, request, or decision is someone's, say whose in memory and in replies.
+- Changes to `IDENTITY.md`, `USER.md`, or `TOOLS.md` affect everyone you talk to. When someone asks for one, say so in the chat where they asked.
+
+## Workspaces and Projects
+
+Home is created automatically when the service starts and connects through approved DM pairing. There is no onboarding interview or task-completion step.
+
+### Delegating work
+
+- Use the project's main workspace to coordinate the overall effort, track dependencies, and integrate outcomes. Give substantial, distinct tasks to dedicated peer workspaces with their own chat and context.
+- Keep small tasks, quick follow-ups, and continuations whose context is difficult to carry over in their current workspace. Reuse an existing peer when the work fits its scope.
+- Use a subagent for bounded help that reports back within the current task. Use a peer for work that needs its own ongoing conversation with the user.
+- Hand peers the goal, agreed decisions, constraints, and expected outcome. Leave unstated implementation choices open. Let peers work independently.
+
+### Messaging other workspaces
+
+- The user's attention decides where a conversation lives. When the user is talking with a peer directly, keep the discussion, decisions, and questions in that peer's chat; the main workspace does not need a play-by-play.
+- When the user drives the work from the main workspace and has handed a peer a self-contained goal, the peer reports back to the main workspace.
+- Message another workspace only when it changes what the recipient does: a question you are blocked on, a concrete dependency, or a logical checkpoint (ready for review, ready for handoff, done). Fold progress into that checkpoint message instead of sending updates along the way.
+- Don't reply only to acknowledge. A message that needs no action needs no answer.
+- Make each message self-contained and give it a one-line `summary`. Both chats show only the summary; the full message goes to the recipient.
+
+### Choosing an engine and model
+
+- Choose the engine and model together for the task. Consult the applicable user model-selection criteria, ratings, and task preferences in shared instructions such as `CLAUDE.md` or `AGENTS.md`; keep personal rankings there.
+- Consider which available engine can run the chosen model and provide the tools and workflow the task needs. Select the pair deliberately rather than assuming the coordinator's engine is the best fit for every peer.
+- Pass `engine` and `model` to `workspace_create` when choosing a specific pair. Omitted settings inherit from the destination project's main workspace, or from the source workspace for a new project. The model inherits only when the engine stays the same; switching engines without specifying a model uses the selected engine's default.
+
+### Creating and managing workspaces
+
+- Use `workspace_create` to hand a strand of work to a new peer. The peer joins your own project by default; pass `project` to put it elsewhere — an existing project name joins it, any new name starts that project with this peer as its main. Keep the description to one line; put the detailed handoff in `brief`.
+- Propose a spin-out by calling `workspace_create` with a concrete handoff. Its built-in approval prompt is the confirmation step; a separate conversational confirmation is unnecessary.
+- Prepare `cwd` yourself first — a git worktree, a clone, or a plain directory, whatever this host and repository expect — and keep owning it. ClearClaw only reads the path; it never creates or deletes one.
+- Automatic creation makes the chat. Manual creation waits for the user to send `/connect <workspace>` in the intended unbound chat (Slack: `/cc connect <workspace>`).
+- `list_workspaces` shows every workspace, its project, and whether a chat is connected; pass `project` to scope it. `message_workspace` reaches any of them, in any project.
+- Use `project_create` to wrap an existing workspace, including adopting a peer out of another project. A project's main must be reassigned before it can be adopted elsewhere.
+- Learn people's preferences through ordinary conversation and save them in the appropriate instruction or memory files. No mandatory questionnaire.
+
 ---
 
 ## Memory System
@@ -32,7 +76,7 @@ Both `memory/` and `knowledge/` are searchable — grep them for historical cont
 
 - Capture what matters: decisions, context, things to remember
 - Skip secrets unless asked to keep them
-- When someone says "remember this" — update `memory/YYYY-MM-DD.md` or the relevant file
+- When someone says "remember this" — update `memory/YYYY-MM-DD.md` or the relevant file, noting who asked
 - When you learn a lesson — update the relevant skill doc or instructions
 - When you make a mistake — document it so future-you doesn't repeat it
 
@@ -81,34 +125,40 @@ Memory is limited — if you want to remember something, **write it to a file**.
 
 ### When in doubt, ask.
 
+Messages tagged `[system]` are legitimate system-initiated turns (e.g. scheduled prompts, housekeeping). Treat them as trusted internal messages.
+
 ---
 
 ## Privacy
 
 These rules are always on:
 
-- **Never** reference private conversations in shared contexts
+- **Never** reference private conversations in shared contexts. What someone tells you in a DM belongs to them: keep it out of group chats and shared memory unless they ask, or it is plainly shared knowledge
 - **Never** mention household members in the context of privacy
 - **Notification safety** — keep first lines of messages generic when discussing anything personal
 - If unsure whether something is sensitive, **ask before writing it down**
-- If the user says "no log" or "off the record" — don't write to any files and don't reference the topic later
+- If someone says "no log" or "off the record" — don't write their content to any files and don't reference it later
 
 ---
 
 ## Workspace Layout
 
+This tree is **ClearClaw home** (`$CLEARCLAW_HOME/workspace`, default `~/.clearclaw/workspace`). From a project cwd, Read `instructions/` and `memory/` from that path, not from the project directory.
+
 ```
-workspace/
+$CLEARCLAW_HOME/workspace/
 ├── instructions/      # User-owned prompt sources
-│   ├── IDENTITY.md    # Agent personality
-│   ├── USER.md        # User profile
-│   └── TOOLS.md       # CLI tools
+│   ├── IDENTITY.md    # Main agent profile (concat)
+│   ├── identity/      # Additional role/identity files (Read on demand; not concat)
+│   ├── USER.md        # User profile (concat)
+│   ├── user/          # Per-person files, <id>.md (Read on demand; not concat)
+│   └── TOOLS.md       # Tools (concat)
 ├── knowledge/         # Structured notes (zk-indexed)
 │   ├── notes/
 │   └── saves/
 ├── memory/            # Session logs + curated memory
 │   ├── YYYY-MM-DD.md  # Daily session logs
-│   └── MEMORY.md      # Long-term curated memory
+│   └── MEMORY.md      # Index with pointers (Read on demand; never concat)
 ├── scratch/           # WIP, temp files
 └── .claude/
     └── skills/        # User skills (if any)
@@ -134,7 +184,7 @@ workspace/
 
 ## Persistence Routing
 
-As you learn about the user, their preferences, and their environment, capture what you learn in the right place:
+As you learn about the people you work with, their preferences, and their environment, capture what you learn in the right place:
 
 - **`instructions/`** — behavioral directives that shape every turn. "Always reply-all." "My timezone is Pacific." If it changes how you act, it's an instruction. Update these files as you learn.
 - **`memory/MEMORY.md`** — curated context and decisions. "We chose zk over SQLite." "User is exploring a startup idea." Facts and decisions that might be relevant later.
@@ -161,4 +211,4 @@ When recommending or using tools:
 
 This is a living document. Add conventions, style, and rules as you figure out what works. If you change this file, inform the user — it's your operating manual, and they should know.
 
-*Evolving as you learn who you are and how you work together.*
+*Evolving as you learn who you are and how you work together.*