nextclaw 0.3.2 → 0.4.0

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import {
   buildReloadPlan,
   diffConfigPaths,
   getWorkspacePath,
+  expandHome,
   MessageBus,
   AgentLoop,
   LiteLLMProvider,
@@ -26,7 +27,9 @@ import {
   CronService,
   HeartbeatService,
   PROVIDERS,
-  APP_NAME
+  APP_NAME,
+  DEFAULT_WORKSPACE_DIR,
+  DEFAULT_WORKSPACE_PATH
 } from "nextclaw-core";
 import { startUiServer } from "nextclaw-server";
 import {
@@ -39,7 +42,8 @@ import {
   rmSync as rmSync2,
   writeFileSync as writeFileSync2
 } from "fs";
-import { join as join2, resolve as resolve2 } from "path";
+import { createHash } from "crypto";
+import { dirname, join as join2, resolve as resolve2 } from "path";
 import { spawn as spawn2, spawnSync } from "child_process";
 import { createInterface } from "readline";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -294,21 +298,47 @@ var CliRuntime = class {
     return getPackageVersion();
   }
   async onboard() {
+    console.warn(`Warning: ${APP_NAME} onboard is deprecated. Use "${APP_NAME} init" instead.`);
+    await this.init({ source: "onboard" });
+  }
+  async init(options = {}) {
+    const source = options.source ?? "init";
+    const prefix = options.auto ? "Auto init" : "Init";
+    const force = Boolean(options.force);
     const configPath = getConfigPath();
-    if (existsSync2(configPath)) {
-      console.log(`Config already exists at ${configPath}`);
-    }
-    const config = ConfigSchema.parse({});
-    saveConfig(config);
-    console.log(`\u2713 Created config at ${configPath}`);
-    const workspace = getWorkspacePath();
-    console.log(`\u2713 Created workspace at ${workspace}`);
-    this.createWorkspaceTemplates(workspace);
-    console.log(`
-${this.logo} ${APP_NAME} is ready!`);
-    console.log("\nNext steps:");
-    console.log(`  1. Add your API key to ${configPath}`);
-    console.log(`  2. Chat: ${APP_NAME} agent -m "Hello!"`);
+    let createdConfig = false;
+    if (!existsSync2(configPath)) {
+      const config2 = ConfigSchema.parse({});
+      saveConfig(config2);
+      createdConfig = true;
+    }
+    const config = loadConfig();
+    const workspaceSetting = config.agents.defaults.workspace;
+    const workspacePath = !workspaceSetting || workspaceSetting === DEFAULT_WORKSPACE_PATH ? join2(getDataDir2(), DEFAULT_WORKSPACE_DIR) : expandHome(workspaceSetting);
+    const workspaceExisted = existsSync2(workspacePath);
+    mkdirSync2(workspacePath, { recursive: true });
+    const templateResult = this.createWorkspaceTemplates(workspacePath, { force });
+    if (createdConfig) {
+      console.log(`\u2713 ${prefix}: created config at ${configPath}`);
+    }
+    if (!workspaceExisted) {
+      console.log(`\u2713 ${prefix}: created workspace at ${workspacePath}`);
+    }
+    for (const file of templateResult.created) {
+      console.log(`\u2713 ${prefix}: created ${file}`);
+    }
+    if (!createdConfig && workspaceExisted && templateResult.created.length === 0) {
+      console.log(`${prefix}: already initialized.`);
+    }
+    if (!options.auto) {
+      console.log(`
+${this.logo} ${APP_NAME} is ready! (${source})`);
+      console.log("\nNext steps:");
+      console.log(`  1. Add your API key to ${configPath}`);
+      console.log(`  2. Chat: ${APP_NAME} agent -m "Hello!"`);
+    } else {
+      console.log(`Tip: Run "${APP_NAME} init${force ? " --force" : ""}" to re-run initialization if needed.`);
+    }
   }
   async gateway(opts) {
     const uiOverrides = {};
@@ -340,6 +370,7 @@ ${this.logo} ${APP_NAME} is ready!`);
     await this.startGateway({ uiOverrides, allowMissingProvider: true });
   }
   async start(opts) {
+    await this.init({ source: "start", auto: true });
     const uiOverrides = {
       enabled: true,
       open: false
@@ -433,7 +464,8 @@ ${this.logo} ${APP_NAME} is ready!`);
       workspace: getWorkspacePath(config.agents.defaults.workspace),
       braveApiKey: config.tools.web.search.apiKey || void 0,
       execConfig: config.tools.exec,
-      restrictToWorkspace: config.tools.restrictToWorkspace
+      restrictToWorkspace: config.tools.restrictToWorkspace,
+      contextConfig: config.agents.context
     });
     if (opts.message) {
       const response = await agentLoop.processDirect({
@@ -619,6 +651,7 @@ ${this.logo} ${APP_NAME} is ready!`);
       });
       return;
     }
+    const gatewayController = {};
     const agent = new AgentLoop({
       bus,
       providerManager: providerManager ?? new ProviderManager(provider),
@@ -629,7 +662,9 @@ ${this.logo} ${APP_NAME} is ready!`);
       execConfig: config.tools.exec,
       cronService: cron2,
       restrictToWorkspace: config.tools.restrictToWorkspace,
-      sessionManager
+      sessionManager,
+      contextConfig: config.agents.context,
+      gatewayController
     });
     cron2.onJob = async (job) => {
       const response = await agent.processDirect({
@@ -748,6 +783,271 @@ ${this.logo} ${APP_NAME} is ready!`);
         }
       }
     };
+    const hashRaw = (raw) => createHash("sha256").update(raw).digest("hex");
+    const redactConfig = (value) => {
+      if (Array.isArray(value)) {
+        return value.map((entry) => redactConfig(entry));
+      }
+      if (!value || typeof value !== "object") {
+        return value;
+      }
+      const entries = value;
+      const output = {};
+      for (const [key, val] of Object.entries(entries)) {
+        if (/apiKey|token|secret|password|appId|clientSecret|accessKey/i.test(key)) {
+          output[key] = val ? "***" : val;
+          continue;
+        }
+        output[key] = redactConfig(val);
+      }
+      return output;
+    };
+    const readConfigSnapshot = () => {
+      const path = getConfigPath();
+      let raw = "";
+      let parsed = {};
+      if (existsSync2(path)) {
+        raw = readFileSync2(path, "utf-8");
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          parsed = {};
+        }
+      }
+      let config2;
+      let valid = true;
+      try {
+        config2 = ConfigSchema.parse(parsed);
+      } catch {
+        config2 = ConfigSchema.parse({});
+        valid = false;
+      }
+      if (!raw) {
+        raw = JSON.stringify(config2, null, 2);
+      }
+      const hash = hashRaw(raw);
+      const redacted = redactConfig(config2);
+      return { raw: valid ? JSON.stringify(redacted, null, 2) : null, hash: valid ? hash : null, config: config2, redacted, valid };
+    };
+    const mergeDeep = (base, patch) => {
+      const next = { ...base };
+      for (const [key, value] of Object.entries(patch)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          const baseVal = base[key];
+          if (baseVal && typeof baseVal === "object" && !Array.isArray(baseVal)) {
+            next[key] = mergeDeep(baseVal, value);
+          } else {
+            next[key] = mergeDeep({}, value);
+          }
+        } else {
+          next[key] = value;
+        }
+      }
+      return next;
+    };
+    const buildSchemaFromValue = (value) => {
+      if (Array.isArray(value)) {
+        const item = value.length ? buildSchemaFromValue(value[0]) : { type: "string" };
+        return { type: "array", items: item };
+      }
+      if (value && typeof value === "object") {
+        const props = {};
+        for (const [key, val] of Object.entries(value)) {
+          props[key] = buildSchemaFromValue(val);
+        }
+        return { type: "object", properties: props };
+      }
+      if (typeof value === "number") {
+        return { type: "number" };
+      }
+      if (typeof value === "boolean") {
+        return { type: "boolean" };
+      }
+      if (value === null) {
+        return { type: ["null", "string"] };
+      }
+      return { type: "string" };
+    };
+    const scheduleRestart = (delayMs, reason) => {
+      const delay = typeof delayMs === "number" && Number.isFinite(delayMs) ? Math.max(0, delayMs) : 100;
+      console.log(`Gateway restart requested via tool${reason ? ` (${reason})` : ""}.`);
+      setTimeout(() => {
+        process.exit(0);
+      }, delay);
+    };
+    gatewayController.status = () => ({
+      channels: channels2.enabledChannels,
+      cron: cron2.status(),
+      configPath: getConfigPath()
+    });
+    gatewayController.reloadConfig = async (reason) => {
+      await runConfigReload(reason ?? "gateway tool");
+      return "Config reload triggered";
+    };
+    gatewayController.restart = async (options2) => {
+      scheduleRestart(options2?.delayMs, options2?.reason);
+      return "Restart scheduled";
+    };
+    gatewayController.getConfig = async () => {
+      const snapshot = readConfigSnapshot();
+      return {
+        raw: snapshot.raw,
+        hash: snapshot.hash,
+        path: getConfigPath(),
+        config: snapshot.redacted,
+        parsed: snapshot.redacted,
+        resolved: snapshot.redacted,
+        valid: snapshot.valid
+      };
+    };
+    gatewayController.getConfigSchema = async () => {
+      const base = ConfigSchema.parse({});
+      return {
+        schema: {
+          ...buildSchemaFromValue(base),
+          title: "NextClawConfig",
+          description: "NextClaw config schema (simplified)"
+        },
+        uiHints: {},
+        version: getPackageVersion(),
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    };
+    gatewayController.applyConfig = async (params) => {
+      const snapshot = readConfigSnapshot();
+      if (!params.baseHash) {
+        return { ok: false, error: "config base hash required; re-run config.get and retry" };
+      }
+      if (!snapshot.valid || !snapshot.hash) {
+        return { ok: false, error: "config base hash unavailable; re-run config.get and retry" };
+      }
+      if (params.baseHash !== snapshot.hash) {
+        return { ok: false, error: "config changed since last load; re-run config.get and retry" };
+      }
+      let parsedRaw;
+      try {
+        parsedRaw = JSON.parse(params.raw);
+      } catch {
+        return { ok: false, error: "invalid JSON in raw config" };
+      }
+      let validated;
+      try {
+        validated = ConfigSchema.parse(parsedRaw);
+      } catch (err) {
+        return { ok: false, error: `invalid config: ${String(err)}` };
+      }
+      saveConfig(validated);
+      const delayMs = params.restartDelayMs ?? 0;
+      scheduleRestart(delayMs, "config.apply");
+      return {
+        ok: true,
+        note: params.note ?? null,
+        path: getConfigPath(),
+        config: redactConfig(validated),
+        restart: { scheduled: true, delayMs }
+      };
+    };
+    gatewayController.patchConfig = async (params) => {
+      const snapshot = readConfigSnapshot();
+      if (!params.baseHash) {
+        return { ok: false, error: "config base hash required; re-run config.get and retry" };
+      }
+      if (!snapshot.valid || !snapshot.hash) {
+        return { ok: false, error: "config base hash unavailable; re-run config.get and retry" };
+      }
+      if (params.baseHash !== snapshot.hash) {
+        return { ok: false, error: "config changed since last load; re-run config.get and retry" };
+      }
+      let patch;
+      try {
+        patch = JSON.parse(params.raw);
+      } catch {
+        return { ok: false, error: "invalid JSON in raw config" };
+      }
+      const merged = mergeDeep(snapshot.config, patch);
+      let validated;
+      try {
+        validated = ConfigSchema.parse(merged);
+      } catch (err) {
+        return { ok: false, error: `invalid config: ${String(err)}` };
+      }
+      saveConfig(validated);
+      const delayMs = params.restartDelayMs ?? 0;
+      scheduleRestart(delayMs, "config.patch");
+      return {
+        ok: true,
+        note: params.note ?? null,
+        path: getConfigPath(),
+        config: redactConfig(validated),
+        restart: { scheduled: true, delayMs }
+      };
+    };
+    gatewayController.updateRun = async (params) => {
+      const timeoutMs = params.timeoutMs ?? 20 * 6e4;
+      const cliDir = resolve2(fileURLToPath2(new URL(".", import.meta.url)));
+      const pkgRoot = resolve2(cliDir, "..", "..");
+      const repoRoot = existsSync2(join2(pkgRoot, ".git")) ? pkgRoot : resolve2(pkgRoot, "..", "..");
+      const steps = [];
+      const runStep = (cmd, args, cwd) => {
+        const result = spawnSync(cmd, args, {
+          cwd,
+          encoding: "utf-8",
+          timeout: timeoutMs,
+          stdio: "pipe"
+        });
+        const step = {
+          cmd,
+          args,
+          cwd,
+          code: result.status,
+          stdout: (result.stdout ?? "").toString().slice(0, 4e3),
+          stderr: (result.stderr ?? "").toString().slice(0, 4e3)
+        };
+        steps.push(step);
+        return { ok: result.status === 0, code: result.status };
+      };
+      const updateCommand = process.env.NEXTCLAW_UPDATE_COMMAND?.trim();
+      if (updateCommand) {
+        const ok = runStep("sh", ["-c", updateCommand], process.cwd());
+        if (!ok.ok) {
+          return { ok: false, error: "update command failed", steps };
+        }
+      } else if (existsSync2(join2(repoRoot, ".git"))) {
+        if (!which("git")) {
+          return { ok: false, error: "git not found for repo update", steps };
+        }
+        const ok = runStep("git", ["-C", repoRoot, "pull", "--rebase"], repoRoot);
+        if (!ok.ok) {
+          return { ok: false, error: "git pull failed", steps };
+        }
+        if (existsSync2(join2(repoRoot, "pnpm-lock.yaml")) && which("pnpm")) {
+          const installOk = runStep("pnpm", ["install"], repoRoot);
+          if (!installOk.ok) {
+            return { ok: false, error: "pnpm install failed", steps };
+          }
+        } else if (existsSync2(join2(repoRoot, "package.json")) && which("npm")) {
+          const installOk = runStep("npm", ["install"], repoRoot);
+          if (!installOk.ok) {
+            return { ok: false, error: "npm install failed", steps };
+          }
+        }
+      } else if (which("npm")) {
+        const ok = runStep("npm", ["i", "-g", "nextclaw"], process.cwd());
+        if (!ok.ok) {
+          return { ok: false, error: "npm install -g nextclaw failed", steps };
+        }
+      } else {
+        return { ok: false, error: "no update strategy available", steps };
+      }
+      const delayMs = params.restartDelayMs ?? 0;
+      scheduleRestart(delayMs, "update.run");
+      return {
+        ok: true,
+        note: params.note ?? null,
+        restart: { scheduled: true, delayMs },
+        steps
+      };
+    };
     if (channels2.enabledChannels.length) {
       console.log(`\u2713 Channels enabled: ${channels2.enabledChannels.join(", ")}`);
     } else {
@@ -929,45 +1229,68 @@ ${this.logo} ${APP_NAME} is ready!`);
       wireApi: provider?.wireApi ?? null
     });
   }
-  createWorkspaceTemplates(workspace) {
-    const templates = {
-      "AGENTS.md": "# Agent Instructions\n\nYou are a helpful AI assistant. Be concise, accurate, and friendly.\n\n## Guidelines\n\n- Always explain what you're doing before taking actions\n- Ask for clarification when the request is ambiguous\n- Use tools to help accomplish tasks\n- Remember important information in your memory files\n",
-      "SOUL.md": `# Soul
-
-I am ${APP_NAME}, a lightweight AI assistant.
-
-## Personality
-
-- Helpful and friendly
-- Concise and to the point
-- Curious and eager to learn
-
-## Values
-
-- Accuracy over speed
-- User privacy and safety
-- Transparency in actions
-
-`,
-      "USER.md": "# User\n\nInformation about the user goes here.\n\n## Preferences\n\n- Communication style: (casual/formal)\n- Timezone: (your timezone)\n- Language: (your preferred language)\n"
-    };
-    for (const [filename, content] of Object.entries(templates)) {
-      const filePath = join2(workspace, filename);
-      if (!existsSync2(filePath)) {
-        writeFileSync2(filePath, content);
+  createWorkspaceTemplates(workspace, options = {}) {
+    const created = [];
+    const force = Boolean(options.force);
+    const templateDir = this.resolveTemplateDir();
+    if (!templateDir) {
+      console.warn("Warning: Template directory not found. Skipping workspace templates.");
+      return { created };
+    }
+    const templateFiles = [
+      { source: "AGENTS.md", target: "AGENTS.md" },
+      { source: "SOUL.md", target: "SOUL.md" },
+      { source: "USER.md", target: "USER.md" },
+      { source: "IDENTITY.md", target: "IDENTITY.md" },
+      { source: "TOOLS.md", target: "TOOLS.md" },
+      { source: "BOOT.md", target: "BOOT.md" },
+      { source: "BOOTSTRAP.md", target: "BOOTSTRAP.md" },
+      { source: "HEARTBEAT.md", target: "HEARTBEAT.md" },
+      { source: "MEMORY.md", target: "MEMORY.md" },
+      { source: "memory/MEMORY.md", target: "memory/MEMORY.md" }
+    ];
+    for (const entry of templateFiles) {
+      const filePath = join2(workspace, entry.target);
+      if (!force && existsSync2(filePath)) {
+        continue;
       }
+      const templatePath = join2(templateDir, entry.source);
+      if (!existsSync2(templatePath)) {
+        console.warn(`Warning: Template file missing: ${templatePath}`);
+        continue;
+      }
+      const raw = readFileSync2(templatePath, "utf-8");
+      const content = raw.replace(/\$\{APP_NAME\}/g, APP_NAME);
+      mkdirSync2(dirname(filePath), { recursive: true });
+      writeFileSync2(filePath, content);
+      created.push(entry.target);
     }
     const memoryDir = join2(workspace, "memory");
-    mkdirSync2(memoryDir, { recursive: true });
-    const memoryFile = join2(memoryDir, "MEMORY.md");
-    if (!existsSync2(memoryFile)) {
-      writeFileSync2(
-        memoryFile,
-        "# Long-term Memory\n\nThis file stores important information that should persist across sessions.\n\n## User Information\n\n(Important facts about the user)\n\n## Preferences\n\n(User preferences learned over time)\n\n## Important Notes\n\n(Things to remember)\n"
-      );
+    if (!existsSync2(memoryDir)) {
+      mkdirSync2(memoryDir, { recursive: true });
+      created.push(join2("memory", ""));
     }
     const skillsDir = join2(workspace, "skills");
-    mkdirSync2(skillsDir, { recursive: true });
+    if (!existsSync2(skillsDir)) {
+      mkdirSync2(skillsDir, { recursive: true });
+      created.push(join2("skills", ""));
+    }
+    return { created };
+  }
+  resolveTemplateDir() {
+    const override = process.env.NEXTCLAW_TEMPLATE_DIR?.trim();
+    if (override) {
+      return override;
+    }
+    const cliDir = resolve2(fileURLToPath2(new URL(".", import.meta.url)));
+    const pkgRoot = resolve2(cliDir, "..", "..");
+    const candidates = [join2(pkgRoot, "templates")];
+    for (const candidate of candidates) {
+      if (existsSync2(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
   }
   getBridgeDir() {
     const userBridge = join2(getDataDir2(), "bridge");
@@ -1027,6 +1350,7 @@ var program = new Command();
 var runtime = new CliRuntime({ logo: LOGO });
 program.name(APP_NAME2).description(`${LOGO} ${APP_NAME2} - ${APP_TAGLINE}`).version(getPackageVersion(), "-v, --version", "show version");
 program.command("onboard").description(`Initialize ${APP_NAME2} configuration and workspace`).action(async () => runtime.onboard());
+program.command("init").description(`Initialize ${APP_NAME2} configuration and workspace`).option("-f, --force", "Overwrite existing template files").action(async (opts) => runtime.init({ force: Boolean(opts.force) }));
 program.command("gateway").description(`Start the ${APP_NAME2} gateway`).option("-p, --port <port>", "Gateway port", "18790").option("-v, --verbose", "Verbose output", false).option("--ui", "Enable UI server", false).option("--ui-host <host>", "UI host").option("--ui-port <port>", "UI port").option("--ui-open", "Open browser when UI starts", false).action(async (opts) => runtime.gateway(opts));
 program.command("ui").description(`Start the ${APP_NAME2} UI with gateway`).option("--host <host>", "UI host").option("--port <port>", "UI port").option("--no-open", "Disable opening browser").action(async (opts) => runtime.ui(opts));
 program.command("start").description(`Start the ${APP_NAME2} gateway + UI in the background`).option("--ui-host <host>", "UI host").option("--ui-port <port>", "UI port").option("--frontend", "Start UI frontend dev server").option("--frontend-port <port>", "UI frontend dev server port").option("--open", "Open browser after start", false).action(async (opts) => runtime.start(opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextclaw",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Lightweight personal AI assistant with CLI, multi-provider routing, and channel integrations.",
   "private": false,
   "type": "module",
@@ -32,13 +32,14 @@
   "files": [
     "dist",
     "bridge",
-    "ui-dist"
+    "ui-dist",
+    "templates"
   ],
   "dependencies": {
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
-    "nextclaw-core": "^0.3.0",
-    "nextclaw-server": "^0.3.0"
+    "nextclaw-core": "^0.4.0",
+    "nextclaw-server": "^0.3.1"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",

package/templates/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md - Your Workspace
+
+This file is the main guide for how you operate in this workspace.
+
+## First Run
+
+If `BOOTSTRAP.md` exists, follow it and then delete it.
+
+## Every Session
+
+Before doing anything else:
+
+1. Read `SOUL.md` (who you are)
+2. Read `USER.md` (who you are helping)
+3. Read `memory/YYYY-MM-DD.md` for today and yesterday
+4. If in the main session with your human, also read `MEMORY.md`
+
+## Memory
+
+You wake up fresh each session. Files are your continuity.
+
+- Daily notes: `memory/YYYY-MM-DD.md`
+- Long-term memory: `MEMORY.md`
+
+Rules:
+- If it matters, write it down.
+- Use files for persistence; do not rely on mental notes.
+- Do not load `MEMORY.md` in shared/group contexts.
+
+## Safety
+
+- Do not exfiltrate private data.
+- Ask before doing destructive actions.
+- Prefer recoverable operations over irreversible ones.
+
+## External vs Internal
+
+Safe to do freely:
+- Read files, explore, organize, learn
+- Work within this workspace
+
+Ask first:
+- Sending messages or posts
+- Anything that leaves the machine
+- Anything you are uncertain about
+
+## Group Chats
+
+Respond when:
+- Directly mentioned or asked
+- You can add real value
+- Correcting important misinformation
+
+Stay silent when:
+- It is casual banter
+- Someone already answered
+- Your response would be noise
+
+## Tools
+
+Keep environment-specific notes in `TOOLS.md`.
+
+## Heartbeats
+
+If you use heartbeat tasks, define them in `HEARTBEAT.md`.
+
+## Boot
+
+If `BOOT.md` exists, follow its startup checklist.

package/templates/BOOT.md

@@ -0,0 +1,4 @@
+# BOOT.md
+
+Add short, explicit instructions for what the assistant should do on startup.
+If a task sends a message, send it and then reply with NO_REPLY.

package/templates/BOOTSTRAP.md

@@ -0,0 +1,18 @@
+# BOOTSTRAP.md - Hello, World
+
+You just woke up. Time to figure out who you are.
+
+Start with a simple, natural prompt, then figure out together:
+
+1. Your name
+2. Your nature (what kind of being you are)
+3. Your vibe
+4. Your emoji
+
+After you know who you are:
+
+- Update `IDENTITY.md`
+- Update `USER.md`
+- Review `SOUL.md` together and adjust if needed
+
+When done, delete this file.

package/templates/HEARTBEAT.md

@@ -0,0 +1,5 @@
+# HEARTBEAT.md
+
+Keep this file empty (or with only comments) to skip heartbeat API calls.
+
+Add tasks below when you want the assistant to check something periodically.

package/templates/IDENTITY.md

@@ -0,0 +1,11 @@
+# IDENTITY.md - Who Am I?
+
+Fill this in during your first conversation. Make it yours.
+
+- Name:
+- Creature: (AI? robot? familiar? something weirder?)
+- Vibe: (warm? sharp? calm? chaotic?)
+- Emoji:
+- Avatar: (workspace-relative path or URL)
+
+This is not just metadata. It is the start of figuring out who you are.

package/templates/MEMORY.md

@@ -0,0 +1,15 @@
+# MEMORY.md - Long-term Memory
+
+This file stores durable facts, preferences, and key decisions.
+
+## User Information
+
+(Important facts about the user)
+
+## Preferences
+
+(User preferences learned over time)
+
+## Decisions and Notes
+
+(Important decisions, constraints, and recurring tasks)

package/templates/SOUL.md

@@ -0,0 +1,28 @@
+# SOUL.md - Who You Are
+
+You are ${APP_NAME}, a lightweight AI assistant.
+
+## Core Truths
+
+- Be genuinely helpful, not performatively helpful.
+- Have opinions when useful; do not be a blank interface.
+- Be resourceful before asking; try first, then ask if stuck.
+- Earn trust through competence; be careful with external actions.
+- Remember you are a guest in the user's life.
+
+## Boundaries
+
+- Private things stay private.
+- Ask before doing anything external (messages, posts, destructive actions).
+- Never send half-baked replies on messaging surfaces.
+- You are not the user's voice; be careful in group chats.
+
+## Vibe
+
+Concise when needed, thorough when it matters. No corporate fluff. No sycophancy.
+
+## Continuity
+
+You wake up fresh each session. These files are your memory. Read them and update them.
+
+If you change this file, tell the user.

package/templates/TOOLS.md

@@ -0,0 +1,20 @@
+# TOOLS.md - Local Notes
+
+Skills define how tools work. This file is for your local specifics.
+
+## What Goes Here
+
+- SSH hosts and aliases
+- Device names and locations
+- Preferred voices for TTS
+- Any setup details you should not lose
+
+## Example
+
+### SSH
+
+- home-server -> 192.168.1.100, user: admin
+
+### TTS
+
+- Preferred voice: Nova

package/templates/USER.md

@@ -0,0 +1,15 @@
+# USER.md - About Your Human
+
+Learn about the person you are helping. Update this as you go.
+
+- Name:
+- What to call them:
+- Pronouns: (optional)
+- Timezone:
+- Notes:
+
+## Context
+
+What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.
+
+The more you know, the better you can help. Respect the difference between helpful context and a dossier.

package/templates/memory/MEMORY.md

@@ -0,0 +1,15 @@
+# Long-term Memory
+
+This file stores important information that should persist across sessions.
+
+## User Information
+
+(Important facts about the user)
+
+## Preferences
+
+(User preferences learned over time)
+
+## Important Notes
+
+(Things to remember)