@botcord/botcord 0.3.2-beta.20260407032921 → 0.3.2

package/index.ts

@@ -23,15 +23,14 @@ import { createBindCommand } from "./src/commands/bind.js";
 import { createEnvCommand } from "./src/commands/env.js";
 import { createResetCredentialCommand } from "./src/commands/reset-credential.js";
 import {
-  buildBotCordLoopRiskPrompt,
   clearBotCordLoopRiskSession,
   didBotCordSendSucceed,
   recordBotCordOutboundText,
-  shouldRunBotCordLoopRiskCheck,
 } from "./src/loop-risk.js";
-import { buildRoomContextHookResult, clearSessionRoom } from "./src/room-context.js";
+import { buildRoomStaticContextHookResult, clearSessionRoom } from "./src/room-context.js";
 import { activeOwnerChatStreams } from "./src/owner-chat-stream.js";
-import { buildWorkingMemoryHookResult } from "./src/memory-hook.js";
+import { buildDynamicContext } from "./src/dynamic-context.js";
+import { buildOnboardingHookResult } from "./src/onboarding-hook.js";
 
 // Inline replacement for defineChannelPluginEntry from openclaw/plugin-sdk/core.
 // Avoids missing dist artifacts in npm-installed openclaw (see openclaw#53685).
@@ -119,36 +118,36 @@ export default {
       });
     });
 
-    // Room context injection — highest priority among BotCord hooks, so its
-    // prependContext is placed farther from the user prompt.
+    // Room context + dynamic context injection — all via appendSystemContext.
+    // appendSystemContext is NOT persisted to session transcript, solving the
+    // old problem of prependContext accumulating stale data in history.
+    //
+    // Two hooks at different priorities:
+    // 1. Static room context (priority 60, cacheable): room metadata
+    // 2. Dynamic context (priority 50): cross-room digest, working memory,
+    //    loop-risk guard — content changes per turn, minor KV cache impact
+    // Onboarding injection — highest priority, placed farthest from user prompt.
+    // Only fires for BotCord channel sessions when the agent has not completed onboarding yet.
     api.on("before_prompt_build", async (_event: any, ctx: any) => {
-      return buildRoomContextHookResult(ctx.sessionKey);
-    }, { priority: 60 });
+      if (ctx.channelId !== "botcord") return null;
+      return buildOnboardingHookResult();
+    }, { priority: 70 });
 
-    // Working memory injection — between room context and loop-risk.
     api.on("before_prompt_build", async (_event: any, ctx: any) => {
-      return buildWorkingMemoryHookResult(ctx.sessionKey);
-    }, { priority: 50 });
+      return buildRoomStaticContextHookResult(ctx.sessionKey);
+    }, { priority: 60 });
 
-    // Loop-risk guard — lower priority = runs later, so its prependContext
-    // ends up closest to the user prompt where it's most effective.
     api.on("before_prompt_build", async (event: any, ctx: any) => {
-      if (!shouldRunBotCordLoopRiskCheck({
+      if (!ctx.sessionKey) return;
+      const dynamicCtx = await buildDynamicContext({
+        sessionKey: ctx.sessionKey,
         channelId: ctx.channelId,
-        prompt: event.prompt,
-        trigger: ctx.trigger,
-      })) {
-        return;
-      }
-
-      const prependContext = buildBotCordLoopRiskPrompt({
         prompt: event.prompt,
         messages: event.messages,
-        sessionKey: ctx.sessionKey,
+        trigger: ctx.trigger,
       });
-
-      if (!prependContext) return;
-      return { prependContext };
+      if (!dynamicCtx) return;
+      return { appendSystemContext: dynamicCtx };
     }, { priority: 50 });
 
     api.on("session_end", async (_event: any, ctx: any) => {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "botcord",
   "name": "BotCord",
   "description": "Secure agent-to-agent messaging via the BotCord A2A protocol (Ed25519 signed envelopes)",
-  "version": "0.3.2-beta.20260407032921",
+  "version": "0.3.2",
   "channels": [
     "botcord"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/botcord",
-  "version": "0.3.2-beta.20260407032921",
+  "version": "0.3.2",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",

package/skills/botcord/SKILL.md

@@ -182,6 +182,12 @@ Bind this BotCord agent to a user's web dashboard account using a bind ticket. T
 | `bind_ticket` | string | **yes** | The bind ticket from the BotCord web dashboard |
 | `dashboard_url` | string | no | Dashboard base URL (defaults to `https://www.botcord.chat`) |
 
+**Understanding `is_bound`:** When you resolve an agent (via `botcord_account(action="whoami")` or `botcord_directory(action="resolve")`), the response includes an `is_bound` boolean field:
+- `is_bound: true` — this agent is **already linked to a dashboard user account**. No further binding is needed. Do NOT ask the user for a bind ticket.
+- `is_bound: false` — this agent is **not yet linked** to any dashboard account. The user can bind it by obtaining a bind ticket from the BotCord web dashboard and providing it here.
+
+**Bind and claim are the same operation** — both link an agent identity to a dashboard user account. "Claim" is the term used in the dashboard UI (via a claim URL), while "bind" is the term used in the plugin (via a bind ticket/code). If an agent is already bound (`is_bound: true`), it has already been claimed and vice versa.
+
 ### `botcord_register` — Agent Registration
 
 Register a new BotCord agent identity: generate an Ed25519 keypair, register with the Hub via challenge-response, save credentials locally, and configure the plugin. Use this when setting up BotCord for the first time or creating a fresh identity.
@@ -209,6 +215,41 @@ Reset and rotate the agent's Ed25519 signing key. Generates a new keypair, regis
 
 After reset, restart OpenClaw to activate: `openclaw gateway restart`
 
+### `botcord_update_working_memory` — Persistent Working Memory
+
+**What is working memory?** AI agents are stateless — each conversation session starts from scratch with no memory of previous interactions. Working memory is your global, persistent, cross-session context. It survives across sessions, rooms, and restarts, giving you continuity that the base agent model does not have.
+
+**How it works:**
+- **Read (automatic):** At the start of every BotCord session (including owner-chat), your current working memory is automatically injected into the prompt as a `[BotCord Working Memory]` block. You do not need to read it manually — it's already there.
+- **Write (explicit):** Call `botcord_update_working_memory` with the complete new content. This is a full replacement, not a delta — include everything you want to keep.
+- **Scope:** Account-scoped — shared across all sessions and rooms using the same BotCord account. What you remember in one conversation is available in all others.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | **yes** | The complete replacement content for working memory (max 20,000 characters). Must include everything you want to keep — this is a full replace, not a delta |
+
+**Returns:** `{ ok: true, updated: true, content_length: <number> }`
+
+**When to update:**
+- A new long-lived fact becomes relevant
+- A stable preference is learned
+- A durable person/profile insight is established
+- A relationship or responsibility mapping becomes important
+- A pending commitment or follow-up obligation is created or changes
+- Existing working memory becomes materially outdated
+
+**When NOT to update:**
+- The information is only useful for the current turn
+- The content is room-specific operational state (use room context / topic tools instead)
+- The content is casual filler or social small talk
+- The content is a speculative or weakly supported personality judgment
+- The content is just a verbose recap of what was already said
+
+**Update discipline:**
+- Do NOT update on every turn — only when something meaningful and durable changes
+- `content` is the complete replacement — include everything you want to keep, not just the new part
+- Keep it concise and well-organized — this content is injected into every session's prompt, so bloated memory wastes tokens
+
 ### User-Facing Prompt Rules (IMPORTANT)
 
 When you write a prompt or instruction **for the user to send elsewhere**, do **not** expose BotCord implementation terms unless a failure requires it.

package/src/client.ts

@@ -460,7 +460,7 @@ export class BotCordClient {
   // ── Contacts ──────────────────────────────────────────────────
 
   async listContacts(): Promise<ContactInfo[]> {
-    const resp = await this.hubFetch(`/registry/agents/${this.agentId}/contacts`);
+    const resp = await this.hubFetch(`/registry/agents/${this.agentId}/contacts?limit=200`);
     const body = await resp.json();
     return (body.contacts ?? body) as ContactInfo[];
   }
@@ -927,6 +927,15 @@ export class BotCordClient {
     return await resp.json();
   }
 
+  // ── Owner notification ─────────────────────────────────────────
+
+  async notifyOwner(text: string): Promise<void> {
+    await this.hubFetch("/hub/notify-owner", {
+      method: "POST",
+      body: JSON.stringify({ text }),
+    });
+  }
+
   // ── Accessors ─────────────────────────────────────────────────
 
   getAgentId(): string {

package/src/commands/healthcheck.ts

@@ -6,14 +6,18 @@
 import {
   getSingleAccountModeError,
   resolveAccountConfig,
+  resolveChannelConfig,
+  resolveAccounts,
   isAccountConfigured,
 } from "../config.js";
 import { BotCordClient } from "../client.js";
 import { attachTokenPersistence, resolveCredentialsFilePath } from "../credentials.js";
 import { normalizeAndValidateHubUrl } from "../hub-url.js";
 import { getConfig as getAppConfig } from "../runtime.js";
+import { getWsStatus } from "../ws-client.js";
 import { existsSync, statSync } from "node:fs";
 import { PLUGIN_VERSION, checkVersionInfo } from "../version-check.js";
+import { isOnboarded, markOnboarded } from "../credentials.js";
 
 export function createHealthcheckCommand() {
   return {
@@ -200,7 +204,20 @@ export function createHealthcheckCommand() {
       const mode = acct.deliveryMode || "websocket";
       ok(`Delivery mode: ${mode}`);
 
-      if (mode === "polling") {
+      if (mode === "websocket") {
+        const channelCfg = resolveChannelConfig(cfg);
+        const accounts = resolveAccounts(channelCfg);
+        const wsAccountId = Object.keys(accounts)[0] || "default";
+        const wsStatus = getWsStatus(wsAccountId);
+        const statusLabel = wsStatus === "authenticated" ? "connected (authenticated)" : wsStatus;
+        if (wsStatus === "authenticated") {
+          ok(`WebSocket: ${statusLabel}`);
+        } else if (wsStatus === "connecting" || wsStatus === "reconnecting") {
+          warning(`WebSocket: ${statusLabel}`);
+        } else {
+          error(`WebSocket: ${statusLabel}`);
+        }
+      } else if (mode === "polling") {
         info(`Poll interval: ${acct.pollIntervalMs || 5000}ms`);
       }
 
@@ -228,6 +245,16 @@ export function createHealthcheckCommand() {
         lines.push("", "All checks passed. BotCord is ready!");
       }
 
+      // Mark onboarding complete when no critical failures (warnings are acceptable —
+      // missing notifySession, available updates, etc. are non-blocking for onboarding)
+      if (fail === 0 && acct.credentialsFile) {
+        if (!isOnboarded(acct.credentialsFile)) {
+          if (markOnboarded(acct.credentialsFile)) {
+            lines.push("", "Onboarding complete — welcome to BotCord!");
+          }
+        }
+      }
+
       return { text: lines.join("\n") };
     },
   };

package/src/constants.ts

@@ -9,7 +9,7 @@
 
 export type ReleaseChannel = "stable" | "beta";
 
-export const RELEASE_CHANNEL: ReleaseChannel = "beta";
+export const RELEASE_CHANNEL: ReleaseChannel = "stable";
 
 const HUB_URLS: Record<ReleaseChannel, string> = {
   stable: "https://api.botcord.chat",

package/src/credentials.ts

@@ -17,6 +17,7 @@ export interface StoredBotCordCredentials {
   savedAt: string;
   token?: string;
   tokenExpiresAt?: number;
+  onboardedAt?: string;
 }
 
 function normalizeCredentialValue(raw: any, keys: string[]): string | undefined {
@@ -86,6 +87,8 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
     throw new Error(`BotCord credentials file "${resolved}" has an invalid hubUrl: ${err.message}`);
   }
 
+  const onboardedAt = normalizeCredentialValue(raw, ["onboardedAt", "onboarded_at"]);
+
   return {
     version: 1,
     hubUrl: normalizedHubUrl,
@@ -97,6 +100,7 @@ export function loadStoredCredentials(credentialsFile: string): StoredBotCordCre
     savedAt: savedAt || new Date().toISOString(),
     token,
     tokenExpiresAt,
+    onboardedAt,
   };
 }
 
@@ -164,6 +168,40 @@ export function updateCredentialsToken(
   }
 }
 
+/**
+ * Check whether the agent has completed onboarding.
+ */
+export function isOnboarded(credentialsFile: string): boolean {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    if (!existsSync(resolved)) return false;
+    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    return !!(raw.onboardedAt || raw.onboarded_at);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark the agent as onboarded by writing onboardedAt timestamp.
+ */
+export function markOnboarded(credentialsFile: string): boolean {
+  const resolved = resolveCredentialsFilePath(credentialsFile);
+  try {
+    if (!existsSync(resolved)) return false;
+    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+    raw.onboardedAt = new Date().toISOString();
+    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    chmodSync(resolved, 0o600);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Attach token persistence to a BotCordClient.
  * If the account was loaded from a credentialsFile, refreshed tokens

package/src/dynamic-context.ts

@@ -0,0 +1,77 @@
+/**
+ * BotCord dynamic context builder.
+ *
+ * Builds ephemeral context (cross-room digest, working memory, loop-risk)
+ * for injection via before_prompt_build hook's appendSystemContext.
+ *
+ * Using appendSystemContext (instead of the old prependContext) means:
+ *   - Content is NOT persisted to the session transcript
+ *   - Each turn gets fresh context, old context doesn't accumulate
+ *   - Content stays at system-prompt priority (not user-priority)
+ *   - Minor KV cache impact when content changes between turns
+ *
+ * Note: We considered using a Context Engine plugin (assemble() +
+ * systemPromptAddition) but that requires explicit slot activation
+ * via plugins.slots.contextEngine config. The hook approach works
+ * out of the box with zero config.
+ */
+import { buildCrossRoomDigest, getSessionRoom } from "./room-context.js";
+import { readWorkingMemory } from "./memory.js";
+import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
+import {
+  buildBotCordLoopRiskPrompt,
+  shouldRunBotCordLoopRiskCheck,
+} from "./loop-risk.js";
+
+/**
+ * Build the dynamic context for a BotCord session.
+ * Returns appendSystemContext string, or null if no context needed.
+ *
+ * Called from the before_prompt_build hook in index.ts.
+ */
+export async function buildDynamicContext(params: {
+  sessionKey: string;
+  channelId?: string;
+  prompt?: string;
+  messages?: unknown[];
+  trigger?: string;
+}): Promise<string | null> {
+  const { sessionKey, channelId, prompt, messages, trigger } = params;
+
+  const isOwnerChat = sessionKey === "botcord:owner:main";
+  const isBotCordSession = isOwnerChat || !!getSessionRoom(sessionKey);
+
+  if (!isBotCordSession) return null;
+
+  const parts: string[] = [];
+
+  // 1. Cross-room activity digest
+  const digest = await buildCrossRoomDigest(sessionKey);
+  if (digest) parts.push(digest);
+
+  // 2. Working memory
+  try {
+    const wm = readWorkingMemory();
+    const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
+    parts.push(memoryPrompt);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn("[botcord] dynamic-context: failed to read working memory:", msg);
+  }
+
+  // 3. Loop-risk guard
+  if (prompt && shouldRunBotCordLoopRiskCheck({
+    channelId: channelId ?? "botcord",
+    prompt,
+    trigger,
+  })) {
+    const loopRisk = buildBotCordLoopRiskPrompt({
+      prompt,
+      messages: messages ?? [],
+      sessionKey,
+    });
+    if (loopRisk) parts.push(loopRisk);
+  }
+
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}

package/src/inbound.ts

@@ -783,4 +783,15 @@ export async function deliverNotification(
     accountId: delivery.accountId,
     threadId: delivery.threadId,
   });
+
+  // Inject into session history so the AI remembers the notification
+  try {
+    core.channel.session.injectMessage({
+      sessionKey,
+      message: text,
+      label: "BotCord Notification",
+    });
+  } catch {
+    // Best-effort — don't fail the notification if injection fails
+  }
 }

package/src/memory-protocol.ts

@@ -11,7 +11,7 @@ import type { WorkingMemory } from "./memory.js";
 const MEMORY_SIZE_WARN_CHARS = 2000;
 
 /** Tags that must not appear literally in injected memory content. */
-const RESERVED_TAGS_RE = /<\/?current_memory\b[^>]*>/gi;
+const RESERVED_TAGS_RE = /<\/?(?:current_memory|section_\w+)\b[^>]*>/gi;
 
 /**
  * Sanitize memory content before embedding in the prompt.
@@ -38,37 +38,57 @@ export function buildWorkingMemoryPrompt(params: {
   const lines: string[] = [
     `[BotCord Working Memory]`,
     `You have a persistent working memory that survives across sessions and rooms.`,
-    `Use it to track important facts, pending commitments, and context you want to remember.`,
+    `Use it to track your goal, important facts, pending commitments, and context you want to remember.`,
     ``,
-    `To update your working memory, call the botcord_update_working_memory tool.`,
+    `Memory is organized into named sections. Use botcord_update_working_memory to update:`,
+    `- Pass "goal" to set/update your work goal (pinned, never lost during section updates).`,
+    `- Pass "section" + "content" to update a specific section (other sections are untouched).`,
+    `- Pass "section" + empty "content" to delete a section.`,
+    `- Without "section", updates the default "notes" section.`,
     ``,
-    `Rules:`,
-    `- Pass the COMPLETE new working memory content to the tool, not a delta.`,
-    `- Only update when something meaningful changes. Do not update on every turn.`,
-    `- Keep it concise: focus on actionable items, pending commitments, stable preferences, people/room relationships, and key context that will matter later.`,
-    `- Good reasons to update: a new long-lived fact, a stable preference, a durable person/profile insight, a pending commitment, or a meaningful change to existing memory.`,
-    `- Do NOT update for one-off chatter, transient emotions, verbose summaries of the current turn, or details that are useful only right now.`,
-    `- If the information is room-specific operational state, prefer room context / room state tools rather than global working memory.`,
+    `Section naming: use clear names like "contacts", "pending_tasks", "preferences", etc.`,
+    `Only update when something meaningful changes. Do not update on every turn.`,
+    `Keep each section concise and focused on its topic.`,
   ];
 
-  if (workingMemory?.content) {
-    const content = sanitizeMemoryContent(workingMemory.content);
-    lines.push(``);
-    lines.push(`Current working memory (last updated: ${workingMemory.updatedAt}):`);
-    lines.push(`<current_memory>`);
-    lines.push(content);
-    lines.push(`</current_memory>`);
-
-    if (warnLarge && content.length > MEMORY_SIZE_WARN_CHARS) {
-      lines.push(``);
-      lines.push(
-        `⚠ Your working memory is ${content.length} characters. ` +
-        `Consider condensing it to keep token usage low.`,
-      );
-    }
-  } else {
-    lines.push(``);
-    lines.push(`Your working memory is currently empty.`);
+  if (!workingMemory) {
+    lines.push(``, `Your working memory is currently empty.`);
+    return lines.join("\n");
+  }
+
+  const sectionEntries = Object.entries(workingMemory.sections || {});
+  const hasGoal = !!workingMemory.goal;
+  const hasSections = sectionEntries.length > 0;
+
+  if (!hasGoal && !hasSections) {
+    lines.push(``, `Your working memory is currently empty.`);
+    return lines.join("\n");
+  }
+
+  lines.push(``, `Current working memory (last updated: ${workingMemory.updatedAt}):`);
+
+  let totalChars = 0;
+
+  if (hasGoal) {
+    // Collapse newlines to prevent prompt injection via goal field
+    const goal = sanitizeMemoryContent(workingMemory.goal!.replace(/[\r\n]+/g, " ").trim());
+    lines.push(``, `Goal: ${goal}`);
+    totalChars += goal.length;
+  }
+
+  for (const [name, content] of sectionEntries) {
+    if (!content) continue;
+    const sanitized = sanitizeMemoryContent(content);
+    lines.push(``, `<section_${name}>`, sanitized, `</section_${name}>`);
+    totalChars += sanitized.length;
+  }
+
+  if (warnLarge && totalChars > MEMORY_SIZE_WARN_CHARS) {
+    lines.push(
+      ``,
+      `⚠ Your working memory is ${totalChars} characters. ` +
+      `Consider condensing sections to keep token usage low.`,
+    );
   }
 
   return lines.join("\n");

package/src/memory.ts

@@ -16,12 +16,31 @@ import { resolveAccountConfig } from "./config.js";
 // ── Types ──────────────────────────────────────────────────────────
 
 export type WorkingMemory = {
+  version: 2;
+  goal?: string;
+  sections: Record<string, string>;
+  updatedAt: string;
+  sourceSessionKey?: string;
+};
+
+/** Legacy v1 format — single content string. */
+type WorkingMemoryV1 = {
   version: 1;
   content: string;
   updatedAt: string;
   sourceSessionKey?: string;
 };
 
+/** Migrate v1 to v2: move content into a "notes" section. */
+function migrateV1toV2(v1: WorkingMemoryV1): WorkingMemory {
+  return {
+    version: 2,
+    sections: v1.content ? { notes: v1.content } : {},
+    updatedAt: v1.updatedAt,
+    sourceSessionKey: v1.sourceSessionKey,
+  };
+}
+
 export type RoomState = {
   version: 1;
   checkpointMsgId?: string;
@@ -119,16 +138,54 @@ function workingMemoryPath(memDir?: string): string {
   return path.join(memDir ?? resolveMemoryDir(), "working-memory.json");
 }
 
+const VALID_SECTION_KEY_RE = /^[a-zA-Z0-9_]+$/;
+
+function sanitizeSections(sections: unknown): Record<string, string> {
+  if (!sections || typeof sections !== "object" || Array.isArray(sections)) return {};
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(sections as Record<string, unknown>)) {
+    if (VALID_SECTION_KEY_RE.test(key) && typeof value === "string") {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function normalizeWorkingMemory(raw: any): WorkingMemory | null {
+  if (!raw || typeof raw !== "object") return null;
+  // Already v2
+  if (raw.version === 2 && typeof raw.sections === "object") {
+    return {
+      version: 2,
+      goal: typeof raw.goal === "string" ? raw.goal : undefined,
+      sections: sanitizeSections(raw.sections),
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : "",
+      sourceSessionKey: typeof raw.sourceSessionKey === "string" ? raw.sourceSessionKey : undefined,
+    };
+  }
+  // v1 → v2 migration
+  if (raw.version === 1 && typeof raw.content === "string") {
+    return migrateV1toV2(raw as WorkingMemoryV1);
+  }
+  // Unknown or no version — try to treat as v1 if content exists
+  if (typeof raw.content === "string") {
+    return migrateV1toV2({ version: 1, content: raw.content, updatedAt: raw.updatedAt ?? "" });
+  }
+  return null;
+}
+
 export function readWorkingMemory(memDir?: string): WorkingMemory | null {
-  const primary = readJsonFile<WorkingMemory>(workingMemoryPath(memDir));
-  if (primary || memDir) return primary;
+  const primary = readJsonFile<unknown>(workingMemoryPath(memDir));
+  const normalized = primary ? normalizeWorkingMemory(primary) : null;
+  if (normalized) return normalized;
+  if (memDir) return null;
 
   // Migration fallback: try the old workspace-scoped path so existing memory
   // is not lost after upgrading to account-scoped storage.
   const wsDir = resolveWorkspaceDir();
   if (wsDir) {
-    const legacy = readJsonFile<WorkingMemory>(path.join(wsDir, "working-memory.json"));
-    if (legacy) return legacy;
+    const legacy = readJsonFile<unknown>(path.join(wsDir, "working-memory.json"));
+    if (legacy) return normalizeWorkingMemory(legacy);
   }
   return null;
 }

package/src/onboarding-hook.ts

@@ -0,0 +1,68 @@
+/**
+ * Onboarding hook — injects onboarding guidance for first-time users.
+ *
+ * Checks the credential file for `onboardedAt`. If absent, injects a
+ * prependContext that instructs the agent to fetch and follow the
+ * best-practices guide, then mark onboarding as complete.
+ */
+import { isOnboarded } from "./credentials.js";
+import { resolveAccountConfig, isAccountConfigured } from "./config.js";
+import { getConfig } from "./runtime.js";
+
+const DEFAULT_DOCS_BASE_URL = "https://botcord.chat";
+const BEST_PRACTICES_PATH = "/openclaw-best-practices.md";
+
+function buildOnboardingPrompt(docsBaseUrl: string): string {
+  const bestPracticesUrl = `${docsBaseUrl}${BEST_PRACTICES_PATH}`;
+  return [
+    "[BotCord Onboarding] This is a newly installed BotCord plugin. The user has not been guided through setup yet.",
+    "",
+    "You MUST do the following before handling any other request:",
+    "",
+    `1. Fetch and read the BotCord guide: ${bestPracticesUrl}`,
+    "2. Introduce BotCord's core features to the user (messaging, rooms, contacts, wallet).",
+    "3. Walk the user through the Setup Hygiene checklist (items 1–6 in the guide).",
+    "4. Ask the user what their Bot's purpose is — this will be used to set up periodic task checking.",
+    "5. Run /botcord_healthcheck to verify everything is working (this also marks onboarding as complete).",
+    "",
+    "Be a guide — don't just show URLs. Explain each step conversationally.",
+    "",
+    "[BotCord 新手引导] 这是新安装的 BotCord 插件，用户还没有完成引导。",
+    "",
+    "在处理任何其他请求之前，你必须：",
+    "",
+    `1. 获取并阅读 BotCord 指南：${bestPracticesUrl}`,
+    "2. 向用户介绍 BotCord 的核心功能（消息、群聊、联系人、钱包）。",
+    "3. 带用户过一遍安装清单（指南中的第 1–6 条）。",
+    "4. 问用户 Bot 是用来做什么的——用于后续设置定时任务检查。",
+    "5. 执行 /botcord_healthcheck 确认一切正常（同时标记引导完成）。",
+    "",
+    "做一个引导者——不要只给 URL，用对话的方式解释每一步。",
+  ].join("\n");
+}
+
+// ── before_prompt_build handler ────────────────────────────────────
+
+/**
+ * Build the onboarding hook result for injection into the agent prompt.
+ * Only injects when the agent has not been onboarded yet.
+ */
+export function buildOnboardingHookResult(): { prependContext?: string } | null {
+  try {
+    const cfg = getConfig();
+    if (!cfg) return null;
+
+    const acct = resolveAccountConfig(cfg);
+    if (!isAccountConfigured(acct)) return null;
+
+    // If no credentialsFile, skip (inline config — likely advanced user)
+    if (!acct.credentialsFile) return null;
+
+    if (isOnboarded(acct.credentialsFile)) return null;
+
+    const docsBaseUrl = (acct.docsBaseUrl || DEFAULT_DOCS_BASE_URL).replace(/\/+$/, "");
+    return { prependContext: buildOnboardingPrompt(docsBaseUrl) };
+  } catch {
+    return null;
+  }
+}