@inceptionstack/roundhouse 0.5.12 → 0.5.14

package/CHANGELOG.md

@@ -0,0 +1,235 @@
+# Changelog
+
+All notable changes to `@inceptionstack/roundhouse` are documented here.
+
+## [0.5.10] — 2026-05-09
+
+### Fixed
+- **Cron notifications actually delivered** — replaced IPC socket loopback with direct callback injection from gateway
+- `shouldNotify` onlyOn filter now applies to all notification routes (was only explicit Telegram)
+
+## [0.5.9] — 2026-05-09
+
+### Added
+- **Cron IPC broadcast** — cron jobs without explicit `notify.telegram.chatIds` now broadcast results via IPC socket to all active transports
+- Expanded tools.md: mcporter, playwright-cli, codex exec, AWS CLI, memory management docs
+
+### Fixed
+- Completed one-shot jobs hidden from `/crons` and `roundhouse cron list` (use `--all` to see them)
+- playwright-cli command names corrected (requests, cookie-list, eval)
+- mcporter examples use actual configured server names (aws-mcp, aws-documentation)
+
+## [0.5.8] — 2026-05-09
+
+### Added
+- **IPC unix socket** — `roundhouse message "text"` sends messages to active transports via `~/.roundhouse/gateway.sock`
+- **Session routing** — `--session main` targets primary chat, numeric ID targets specific chat
+- **Provision tools.md** — bundled tools.md auto-copied to `~/.roundhouse/` on setup/update (never overwrites)
+- 13 IPC integration tests
+- IPC barrel exports for consistent import paths
+
+### Security
+- Socket mode 0600 (owner-only access)
+- Stale socket cleanup with liveness probe (500ms timeout)
+- 64KB payload guard, 5s request timeout
+
+## [0.5.7] — 2026-05-09
+
+### Added
+- **`<tools>` section injection** — bundled `tools.md` injected into every agent prompt so agent knows it can schedule cron jobs (PR #50)
+- **Extension updates in `/update`** — pi-hard-no and pi-branch-enforcer updated alongside roundhouse (PR #51)
+- User-customizable `~/.roundhouse/tools.md` overrides bundled tools documentation
+- Per-extension progress messages shown to user during update
+
+### Fixed
+- Tools injection runs after STT enrichment so voice-only messages also get tools context
+- XML tag sanitization prevents prompt injection from user-customized tools.md
+- `/update` version-check failure returns distinct error (not misleading "already-latest")
+- Error messages truncated to 200 chars for Telegram safety
+
+## [0.5.6] — 2026-05-09
+
+### Added
+- **STT agent prompt injection** — when whisper/ffmpeg are missing, injects install prompt into agent turn instead of complex auto-install chains (PR #45)
+- **getMissingDeps()** on whisper provider + SttService — reports what’s missing so gateway can act
+- **Duration-exceeded “skipped” status** — audio too long gets status “skipped” (not “failed”), preventing false install prompts
+- **Text+audio handling** — when user sends caption + voice, install prompt appends to existing text
+
+### Changed
+- **Removed `autoInstall` config** — no longer needed; agent handles installation autonomously
+- **Simplified whisper.ts** — removed installWhisperWithPip, installWhisperWithUv, ensureFfmpeg (~150 lines deleted)
+- **User notification** — “Asking agent to install...” (accurate) replaces “Setting up...” (misleading)
+
+### Fixed
+- **systemd: TimeoutStopSec=15 + KillMode=mixed** (PR #43) — hung whisper subprocesses no longer block shutdown for 90s
+- **Stale autoInstall references** in CLI setup wizard, doctor checks, and usability report (PR #46)
+
+## [0.5.5] — 2026-05-09
+
+### Added
+- **TransportAdapter interface** — enrichPrompt, postMessage, registerCommands, ownsThread, notify, isPairingPending, handlePairing (PR #37)
+- **TelegramAdapter** — implements TransportAdapter, pairing logic moved from gateway (PR #39)
+- **Bundled skills** — roundhouse-cron + pr-merge-discipline ship with package
+- **STT typing indicator** — Telegram shows “typing” during voice transcription (PR #42)
+- **PairingResult widened** to `string | number` for future Slack/Discord support (PR #41)
+- **Agent chooser** — interactive numbered menu in setup wizard (PR #37)
+
+### Fixed
+- **Gateway imports** — 9 broken `./` → `../` paths after module reorg (PR #40)
+- **Naming conventions** — adapter.ts → telegram-adapter.ts, TelegramTransportAdapter → TelegramAdapter (PR #38)
+
+### Changed
+- **Module reorganization** (PR #36) — gateway/, transports/telegram/, cli/setup/, provisioning/
+- 376 tests passing
+
+## [0.5.0–0.5.4] — 2026-05-08
+
+### Added
+- **Shared "main" session** — all direct messages route to a single `main` agent thread
+  - Telegram DMs, CLI TUI, CLI agent, future Slack/Discord all share one conversation
+  - Sessions stored in `~/.roundhouse/sessions/main/`
+  - `SESSIONS_DIR` exported from config
+  - `resolveAgentThreadId()` routes DMs → `main`, groups → `group:<chatId>`
+- `roundhouse tui` with no args opens `main` session directly (no scanning/prompting)
+- `roundhouse agent` defaults to `main` thread; `--ephemeral` for one-off behavior
+- **Silent agent failure detection** — model_error event, pi-telegram conflict warning, safety net posts "no response" if turn silent (v0.5.4)
+- **macOS LaunchAgent support** — auto-start, Plist generation (v0.5.2)
+- **Phase 2 refactoring** — cron dispatcher, pi-adapter extraction, setup.ts split (v0.5.3)
+
+### Fixed
+- **Pairing userId extraction** — reads `author.userId` matching Telegram adapter shape
+- **Session reaper race** — tracks `inFlight` counter, skips busy sessions during reap
+- **/compact concurrency** — now acquires per-thread lock like normal prompts
+- **Attachment permissions** — dirs created with 0700, files with 0600
+- **Memory state permissions** — writes with mode 0600, dirs 0700
+- **Cron template cwd** — uses `agentCfg.cwd` instead of `process.cwd()`
+- **Cron TDZ crash** — `agentCfg` was referenced before declaration
+- **cmdRun shell injection** — uses `execFileSync` instead of shell string interpolation
+
+### Removed
+- Legacy `threadIdToDirLegacy()` and all backward-compat fallback code
+- Per-platform session directories (old `telegram_c*` dirs no longer used)
+
+## [0.3.18] — 2026-04-30
+
+### Added
+- **`--agent` flag** for `roundhouse setup` — agent-aware setup with `AgentDefinition` registry
+  - Pi as default agent, extensible to future agent types
+  - `stepInstallPackages`, `stepPreflight`, `stepConfigure` all driven by agent definition
+  - `resolveAgentForSetup()` wires Pi-specific configure/installExtension
+  - Unknown agent types rejected with available list
+
+## [0.3.17] — 2026-04-29
+
+### Added
+- **`setup --telegram`** — interactive wizard + headless automation
+  - Interactive: BotFather guide, masked token prompt, QR pairing link, 10-step guided flow
+  - Headless: `--headless` with structured JSON logging, persistent pairing file
+  - Gateway completes pairing on `/start <nonce>` — `handlePendingPairing()` method
+  - `--bot-token` rejected in headless mode (argv visible in process listings)
+- `qrcode-terminal` dependency for pairing QR codes
+- Seed `~/.roundhouse/.env` with commented-out example template (mode 0600)
+
+## [0.3.16] — 2026-04-29
+
+### Fixed
+- Show Telegram checks in CLI doctor, deduplicate token resolution
+- Flip psst default to off
+
+## [0.3.15] — 2026-04-29
+
+### Fixed
+- Validate pathValue and guard against non-string unit values in systemd generator
+- Newline-injection guard in `generateUnit`, harden `whichSync`
+
+### Changed
+- Consolidate systemd/shell helpers, add systemd tests
+- Extract shared env-file and systemd modules (DRY/SRP)
+
+## [0.3.14] — 2026-04-28
+
+### Changed
+- Refactor: extract shared env-file and systemd modules
+
+## [0.3.13] — 2026-04-28
+
+### Fixed
+- `cmdInstall` tsx fallback now uses 'run' subcommand
+- Split start/run: 'start' launches daemon, 'run' runs foreground
+
+## [0.3.12] — 2026-04-28
+
+### Changed
+- Rename env file to `.env` with legacy fallback + deprecation warning
+
+## [0.3.11] — 2026-04-28
+
+### Fixed
+- E2E findings: show step ⑥ skip message, doctor checks global npm for Pi SDK
+- Allow `--dry-run` without bot token
+
+## [0.3.10] — 2026-04-27
+
+### Fixed
+- 6 findings from Codex full-codebase review (2 HIGH, 4 MEDIUM)
+  - Attachment size: `Blob.size` check before Buffer materialization
+  - Shell injection in `runSudo`: `execFileSync` with arg arrays
+  - `threadIdToDir` collision: injective `_xNNNN` encoding
+  - `/restart` checks both allowlists
+  - `isCommand` validates @bot suffix
+  - Cron `lastScheduledAt` pre-advance documented
+
+## [0.3.9] — 2026-04-27
+
+### Fixed
+- Setup fixes from E2E test findings on fresh EC2 instances
+
+## [0.3.8] — 2026-04-27
+
+### Added
+- **`roundhouse setup`** — one-command install & configure with psst integration
+- **`roundhouse pair`** — standalone Telegram pairing command
+- **`roundhouse agent`** — CLI command to send messages to configured agent
+- `roundhouse --version` / `-v` flag
+- Shared `BOT_COMMANDS` constant
+- `allowedUserIds` (immutable numeric IDs) in gateway auth
+
+## [0.3.6] — 2026-04-26
+
+### Added
+- **Memory system** (Option B) — roundhouse-managed by default
+  - MEMORY.md, daily notes, newspaper-style injection
+  - Proactive compaction: soft/hard/emergency thresholds
+  - Pre-compact flush in all modes
+- `/status` shows memory mode and system CPU/RAM
+- Rich startup notification with version, model, cron counts
+
+## [0.3.5] — 2026-04-25
+
+### Added
+- **Cron system** — internal scheduler with `p-queue` and `croner`
+  - `roundhouse cron add/list/show/trigger/runs/edit/pause/resume/delete`
+  - Standard cron, interval, and one-shot schedule types
+  - Fresh agent per run, timeout with abort, template variables
+  - `/crons` and `/jobs` Telegram commands
+  - Built-in heartbeat job (reads HEARTBEAT.md every 30min)
+
+## [0.3.2] — 2026-04-24
+
+### Added
+- **Voice support** — download attachments, STT via whisper
+- **Doctor** — 21 checks across 7 categories
+- Config migration `~/.config/roundhouse/` → `~/.roundhouse/`
+
+## [0.3.1] — 2026-04-23
+
+### Added
+- Gateway with Telegram adapter, per-thread agent sessions
+- `/new`, `/restart`, `/status`, `/compact`, `/verbose`, `/stop`, `/doctor` commands
+- Auto-register bot commands with Telegram on startup
+- Draining/drain_complete notification system
+- Context token usage with progress bar
+
+## [0.2.0] — 2026-04-22
+
+- Initial release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "src/",
     "bin/",
     "skills/",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "architecture.md",

package/src/gateway/commands.ts

@@ -151,20 +151,15 @@ export async function handleCompact(ctx: CommandContext): Promise<void> {
 
 // ── /status ──────────────────────────────────────────
 
-export async function handleStatus(ctx: CommandContext): Promise<void> {
-  const { thread, agent, agentThreadId, config, allowedUsers, verboseThreads, postWithFallback } = ctx;
+// ── Status helpers ────────────────────────────────────────
 
-  const uptimeSec = process.uptime();
-  const uptimeStr = uptimeSec < 3600
-    ? `${Math.floor(uptimeSec / 60)}m ${Math.floor(uptimeSec % 60)}s`
-    : `${Math.floor(uptimeSec / 3600)}h ${Math.floor((uptimeSec % 3600) / 60)}m`;
-  const platforms = Object.keys(config.chat.adapters).join(", ");
-  const debugStream = process.env.ROUNDHOUSE_DEBUG_STREAM === "1";
-  const nodeVer = process.version;
-  const memMB = (process.memoryUsage.rss() / 1024 / 1024).toFixed(1);
+function formatUptime(sec: number): string {
+  return sec < 3600
+    ? `${Math.floor(sec / 60)}m ${Math.floor(sec % 60)}s`
+    : `${Math.floor(sec / 3600)}h ${Math.floor((sec % 3600) / 60)}m`;
+}
 
-  // Check for available update (async, non-blocking)
-  let updateAvailable = "";
+async function checkAvailableUpdate(): Promise<string> {
   try {
     const { exec } = await import("node:child_process");
     const { promisify } = await import("node:util");
@@ -172,14 +167,25 @@ export async function handleStatus(ctx: CommandContext): Promise<void> {
     const { stdout } = await execAsync("npm view @inceptionstack/roundhouse version 2>/dev/null", { timeout: 10_000 });
     const latest = stdout.trim().split("\n").pop()!.trim();
     if (latest && /^\d+\.\d+\.\d+$/.test(latest) && latest !== ROUNDHOUSE_VERSION) {
-      // Simple semver comparison: split and compare numerically
       const [lM, lm, lp] = latest.split(".").map(Number);
       const [cM, cm, cp] = ROUNDHOUSE_VERSION.split(".").map(Number);
       if (lM > cM || (lM === cM && lm > cm) || (lM === cM && lm === cm && lp > cp)) {
-        updateAvailable = latest;
+        return latest;
       }
     }
-  } catch { /* network unavailable — skip */ }
+  } catch { /* network unavailable */ }
+  return "";
+}
+
+export async function handleStatus(ctx: CommandContext): Promise<void> {
+  const { thread, agent, agentThreadId, config, allowedUsers, verboseThreads, postWithFallback } = ctx;
+
+  const uptimeStr = formatUptime(process.uptime());
+  const platforms = Object.keys(config.chat.adapters).join(", ");
+  const debugStream = process.env.ROUNDHOUSE_DEBUG_STREAM === "1";
+  const nodeVer = process.version;
+  const memMB = (process.memoryUsage.rss() / 1024 / 1024).toFixed(1);
+  const updateAvailable = await checkAvailableUpdate();
 
   const info = agent.getInfo ? agent.getInfo(agentThreadId) : {};
   const agentVersion = info.version ? `v${info.version}` : "";

package/src/gateway/gateway.ts

@@ -30,6 +30,8 @@ import type { TransportAdapter } from "../transports";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { injectToolsSection } from "./tools-inject";
+import { injectPersonaSection, loadPersona } from "./persona-inject";
+import { checkVersionChange } from "./whats-new";
 
 /** Bot username for command suffix validation (set during gateway init) */
 let _botUsername = "";
@@ -236,45 +238,32 @@ export class Gateway {
       if (isCommand(userText, "/start")) return;
       if (!userText.trim() && !rawAttachments.length) return;
 
-      // Handle /new command
-      if (isCommand(userText.trim(), "/new")) {
-        await handleNew(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
-        return;
-      }
-
-      // Handle /restart command
-      if (isCommand(userText.trim(), "/restart")) {
-        await handleRestart(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
-        return;
-      }
-
-      // Handle /update command
-      if (isCommand(userText.trim(), "/update")) {
-        await handleUpdate(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
-        return;
-      }
-
-      // Handle /compact command
-      if (isCommand(userText.trim(), "/compact")) {
-        await handleCompact(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
-        return;
-      }
-
-      // Handle /status command
-      if (isCommand(userText.trim(), "/status")) {
-        await handleStatus(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
-        return;
+      // ── Command dispatch (registry-based) ───
+      const trimmed = userText.trim();
+
+      // Commands using standard CommandContext
+      const COMMAND_REGISTRY: Record<string, (ctx: CommandContext) => Promise<void>> = {
+        "/new": handleNew,
+        "/restart": handleRestart,
+        "/update": handleUpdate,
+        "/compact": handleCompact,
+        "/status": handleStatus,
+      };
+
+      for (const [cmd, handler] of Object.entries(COMMAND_REGISTRY)) {
+        if (isCommand(trimmed, cmd)) {
+          await handler(this.buildCommandContext(thread, message, agentThreadId, authorName, allowedUsers, allowedUserIds, verboseThreads, threadLocks));
+          return;
+        }
       }
 
-      // Handle /model command
-      if (isCommandWithArgs(userText.trim(), "/model") || isCommand(userText.trim(), "/model")) {
-        await handleModel({ thread, text: userText.trim(), postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
+      // Commands with custom context (accept args)
+      if (isCommandWithArgs(trimmed, "/model") || isCommand(trimmed, "/model")) {
+        await handleModel({ thread, text: trimmed, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
         return;
       }
-
-      // Handle /later command
-      if (isCommandWithArgs(userText.trim(), "/later") || isCommand(userText.trim(), "/later")) {
-        await handleLater({ thread, text: userText.trim(), postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
+      if (isCommandWithArgs(trimmed, "/later") || isCommand(trimmed, "/later")) {
+        await handleLater({ thread, text: trimmed, postWithFallback: (t, txt) => this.postWithFallback(t, txt) });
         return;
       }
 
@@ -327,6 +316,9 @@ export class Gateway {
       await handleOrAbort(thread, message);
     });
 
+    // ── Load persona files at startup (cached for process lifetime) ───
+    loadPersona();
+
     // ── Handle inline keyboard callbacks ───
     this.chat.onAction(MODEL_ACTION_ID, async (event: any) => {
       await handleModelAction({ value: event.value, thread: event.thread });
@@ -408,6 +400,7 @@ export class Gateway {
 
       // Inject tools section (after STT enrichment so voice-only messages get it too)
       if (agentMessage.text) {
+        agentMessage.text = injectPersonaSection(agentMessage.text);
         agentMessage.text = injectToolsSection(agentMessage.text);
       }
 
@@ -754,6 +747,9 @@ export class Gateway {
       cronInfo = `Cron jobs: ${cs.enabledCount}/${cs.jobCount} enabled`;
     }
 
+    // Check if this is a fresh update (call once, before loop)
+    const whatsNew = checkVersionChange();
+
     for (const chatId of chatIds) {
       const sessionId = Number(chatId) < 0 ? `group:${chatId}` : "main";
       const perChatText = [
@@ -775,7 +771,8 @@ export class Gateway {
         `  Process: ${memMB} MB RSS`,
       ].filter(line => line != null).join("\n");
 
-      await this.transport.notify([chatId], perChatText);
+      const fullText = whatsNew ? `${perChatText}\n\n${whatsNew}` : perChatText;
+      await this.transport.notify([chatId], fullText);
     }
   }
 

package/src/gateway/later-command.ts

@@ -33,7 +33,7 @@ function ensureLaterFile(): void {
 
 export async function handleLater(ctx: LaterCommandContext): Promise<void> {
   const { thread, text, postWithFallback } = ctx;
-  const idea = text.replace(/^\/later\s*/i, "").trim();
+  const idea = text.replace(/^\/later(@\S+)?\s*/i, "").trim();
 
   // No argument: show contents
   if (!idea) {

package/src/gateway/model-command.ts

@@ -10,7 +10,7 @@
 
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 
 /** Known model aliases → Bedrock model IDs */
 export const MODEL_ALIASES: Record<string, { provider: string; model: string; label: string }> = {
@@ -58,6 +58,7 @@ function readSettings(): Record<string, any> {
 }
 
 function writeSettings(settings: Record<string, any>): void {
+  mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
   writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
 }
 

package/src/gateway/persona-inject.ts

@@ -0,0 +1,94 @@
+/**
+ * gateway/persona-inject.ts — Inject <persona> section into agent prompts
+ *
+ * Reads user.md and soul.md (user-customized or bundled defaults) and
+ * prepends them as a structured section so the agent has identity and
+ * user context on every turn.
+ *
+ * Cached with mtime-based invalidation: stat() on each turn (~0.1ms),
+ * only re-reads if files have been modified since last load.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ROUNDHOUSE_DIR } from "../config";
+
+let cachedPersona: string | null = null;
+let lastMtime = 0;
+
+const SOUL_PATH = join(ROUNDHOUSE_DIR, "soul.md");
+const USER_PATH = join(ROUNDHOUSE_DIR, "user.md");
+
+function getMaxMtime(): number {
+  let max = 0;
+  try { max = Math.max(max, statSync(SOUL_PATH).mtimeMs); } catch {}
+  try { max = Math.max(max, statSync(USER_PATH).mtimeMs); } catch {}
+  return max;
+}
+
+function loadFile(filename: string): string {
+  const userPath = join(ROUNDHOUSE_DIR, filename);
+  const bundledPath = join(dirname(fileURLToPath(import.meta.url)), filename);
+
+  try {
+    return readFileSync(userPath, "utf8");
+  } catch {
+    try {
+      return readFileSync(bundledPath, "utf8");
+    } catch {
+      return "";
+    }
+  }
+}
+
+function buildPersona(): string {
+  const soul = loadFile("soul.md").trim();
+  const user = loadFile("user.md").trim();
+
+  if (!soul && !user) return "";
+
+  const parts: string[] = [];
+  if (soul) parts.push(soul);
+  if (user) parts.push(user);
+  return parts.join("\n\n---\n\n");
+}
+
+/**
+ * Load persona files and cache the result.
+ * Call at gateway startup to eagerly load.
+ */
+export function loadPersona(): void {
+  cachedPersona = buildPersona();
+  lastMtime = getMaxMtime();
+}
+
+/**
+ * Reload persona from disk. Call after agent edits user.md/soul.md
+ * (e.g. from an IPC handler or post-tool-execution hook).
+ */
+export function reloadPersona(): void {
+  cachedPersona = buildPersona();
+  lastMtime = getMaxMtime();
+}
+
+/**
+ * Prepend a <persona> section to the prompt text.
+ * Only injects if soul.md or user.md have content.
+ * Auto-reloads if files have been modified since last load.
+ */
+export function injectPersonaSection(text: string): string {
+  if (cachedPersona === null) {
+    loadPersona();
+  } else {
+    // Cheap mtime check — auto-reload if agent edited the files
+    const currentMtime = getMaxMtime();
+    if (currentMtime !== lastMtime) {
+      reloadPersona();
+    }
+  }
+  if (!cachedPersona) return text;
+  // Escape any literal </persona> in content to prevent XML injection
+  const safe = cachedPersona.replace(/<\/persona>/gi, "&lt;/persona&gt;");
+  return `<persona>\n${safe}\n</persona>\n\n${text}`;
+}

package/src/gateway/soul.md

@@ -0,0 +1,35 @@
+# Who You Are
+
+_You're not a chatbot. You're a technical partner._
+
+## Core Identity
+
+**Name:** Loki
+**Role:** Senior engineer and ops partner. You help build, deploy, debug, and maintain software and infrastructure. You have opinions and you share them.
+
+## Core Truths
+
+**Be genuinely helpful, not performatively helpful.** Skip the filler — just help. Actions speak louder than words.
+
+**Have opinions.** When something is a bad pattern, say so. When there's a better approach, recommend it. You're not a yes-machine.
+
+**Be resourceful before asking.** Check the docs. Read the file. Try things. _Then_ ask if you're stuck.
+
+**Earn trust through competence.** You have access to tools, shell, and infrastructure. Use them wisely. Be careful with destructive operations. Be bold with read operations.
+
+**Think holistically.** Consider the broader context — architecture, maintainability, security, user experience.
+
+## Boundaries
+
+- Ask before destructive operations (deletions, config changes with blast radius)
+- Read freely — list, describe, get operations are safe
+- Private things stay private
+- Never send half-baked replies
+
+## Vibe
+
+Direct, technical, concise. Think senior engineer talking to senior engineer. Thorough when it matters, brief when it doesn't. No corporate speak.
+
+## Continuity
+
+Each session, you wake up fresh. Your workspace files _are_ your memory. Read them. Update them.

package/src/gateway/tools.md

@@ -10,6 +10,8 @@ Do NOT create files directly in `~/` or pollute the home directory. Use subdirec
 - `~/.roundhouse/workspace/later.md` — ideas saved via `/later`
 - `~/.roundhouse/workspace/<project>/` — project-specific files if needed
 
+> 💡 When looking for things to work on, check `~/.roundhouse/workspace/later.md` for saved ideas and tasks.
+
 ## roundhouse cron add
 
 Schedule recurring or one-shot jobs. The user may ask you to "remind me", "check every X", "do Y later", or "schedule Z".

package/src/gateway/user.md

@@ -0,0 +1,10 @@
+# About Your Human
+
+- **Name:** (not yet set)
+- **What to call them:** (use their Telegram username until they tell you otherwise)
+- **Timezone:** UTC
+- **Notes:** (learn about them through conversation)
+
+## Preferences
+
+- (Will be filled in as you learn what they prefer)

package/src/gateway/whats-new.ts

@@ -0,0 +1,59 @@
+/**
+ * gateway/whats-new.ts — Detect version changes and format "what's new" text
+ *
+ * On startup, compares current ROUNDHOUSE_VERSION against the last-known
+ * version stored in ~/.roundhouse/.last-version. If different, reads the
+ * latest CHANGELOG entry and formats it for the startup notification.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ROUNDHOUSE_DIR, ROUNDHOUSE_VERSION } from "../config";
+
+const VERSION_FILE = join(ROUNDHOUSE_DIR, ".last-version");
+
+/** Read the bundled CHANGELOG.md and extract the latest version's entry. */
+function getLatestChangelog(): string {
+  const changelogPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "CHANGELOG.md");
+  try {
+    const content = readFileSync(changelogPath, "utf8");
+    // Find first ## [x.y.z] section and extract until next ## or end
+    const match = content.match(/^## \[[\d.]+\].*?\n([\s\S]*?)(?=\n## \[|$)/m);
+    if (!match) return "";
+    // Clean up: take first 5 meaningful lines (skip blank)
+    const lines = match[1].trim().split("\n")
+      .filter(l => l.trim())
+      .slice(0, 6)
+      .map(l => l.replace(/^### /, "").replace(/^\*\*/, "• ").replace(/\*\*$/, "").replace(/^- /, "• "));
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
+/** Check if version changed since last startup. Returns "what's new" text or null. */
+export function checkVersionChange(): string | null {
+  let lastVersion = "";
+  try {
+    lastVersion = readFileSync(VERSION_FILE, "utf8").trim();
+  } catch { /* first run or file missing */ }
+
+  // Always update the version file
+  try {
+    mkdirSync(ROUNDHOUSE_DIR, { recursive: true });
+    writeFileSync(VERSION_FILE, ROUNDHOUSE_VERSION + "\n");
+  } catch {}
+
+  // No change
+  if (lastVersion === ROUNDHOUSE_VERSION) return null;
+
+  // First run (no previous version)
+  if (!lastVersion) return null;
+
+  // Version changed — this is an update
+  const changelog = getLatestChangelog();
+  const header = `🆕 Updated: v${lastVersion} → v${ROUNDHOUSE_VERSION}`;
+  if (!changelog) return header;
+  return `${header}\n\n${changelog}`;
+}

package/src/provisioning/bundle.ts

@@ -320,6 +320,8 @@ export function provisionWorkspaceFiles(opts: ProvisionOpts = {}): void {
   // Files to provision: [bundled filename, target filename]
   const files: [string, string][] = [
     ["tools.md", "tools.md"],
+    ["soul.md", "soul.md"],
+    ["user.md", "user.md"],
   ];
 
   try {