instar 0.3.4 → 0.3.5

package/dist/commands/init.js

@@ -432,6 +432,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Create shell/python scripts in \`.claude/scripts/\` for reusable capabilities.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+curl http://localhost:${port}/capabilities
+\`\`\`
+
+This returns your full capability matrix: scripts, hooks, Telegram status, jobs, relationships, and more. It is the source of truth about what you can do. **Never hallucinate about missing capabilities — verify first.**
+
 ### How to Build New Capabilities
 
 When a user asks for something you can't do yet, **build it**:
@@ -739,6 +749,17 @@ if [ -d "$INSTAR_DIR/relationships" ]; then
   fi
 fi
 CONTEXT="\${CONTEXT}IMPORTANT: To report bugs or request features, use POST /feedback on your local server. NEVER use gh or GitHub directly.\\n"
+
+# Self-discovery: check what capabilities are available
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  PORT=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('port', 4040))" 2>/dev/null || echo "4040")
+  HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+  if [ "$HEALTH" = "200" ]; then
+    CONTEXT="\${CONTEXT}Instar server is running on port \${PORT}. Query your capabilities: curl http://localhost:\${PORT}/capabilities\\n"
+    CONTEXT="\${CONTEXT}IMPORTANT: Before claiming you lack a capability, check /capabilities first.\\n"
+  fi
+fi
+
 [ -n "$CONTEXT" ] && echo "$CONTEXT"
 `, { mode: 0o755 });
     // Dangerous command guard

package/dist/commands/server.js

@@ -268,7 +268,13 @@ export async function startServer(options) {
             });
             console.log(pc.green('  Dispatch system enabled'));
         }
-        const updateChecker = new UpdateChecker(config.stateDir);
+        const updateChecker = new UpdateChecker({
+            stateDir: config.stateDir,
+            projectDir: config.projectDir,
+            port: config.port,
+            hasTelegram: config.messaging.some(m => m.type === 'telegram' && m.enabled),
+            projectName: config.projectName,
+        });
         // Check for updates on startup
         updateChecker.check().then(info => {
             if (info.updateAvailable) {

package/dist/commands/setup.js

@@ -798,6 +798,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Create shell/python scripts in \`.claude/scripts/\` for reusable capabilities.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+curl http://localhost:${port}/capabilities
+\`\`\`
+
+This returns your full capability matrix: scripts, hooks, Telegram status, jobs, relationships, and more. It is the source of truth about what you can do. **Never hallucinate about missing capabilities — verify first.**
+
 ### How to Build New Capabilities
 
 When a user asks for something you can't do yet, **build it**:

package/dist/core/PostUpdateMigrator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Post-Update Migrator — the "intelligence download" layer.
+ *
+ * When an agent installs a new version of instar, updating the npm
+ * package only changes the server code. But the agent's local awareness
+ * lives in project files: CLAUDE.md, hooks, scripts.
+ *
+ * This migrator bridges that gap. After every successful update, it:
+ *   1. Re-installs hooks with the latest templates (behavioral upgrades)
+ *   2. Patches CLAUDE.md with any new sections (awareness upgrades)
+ *   3. Installs any new scripts (capability upgrades)
+ *   4. Returns a human-readable migration report
+ *
+ * Design principles:
+ *   - Additive only: never remove or modify existing user customizations
+ *   - Hooks are overwritten (they're generated infrastructure, not user-edited)
+ *   - CLAUDE.md sections are appended only if missing (check by heading)
+ *   - Scripts are installed only if missing (never overwrite user modifications)
+ */
+export interface MigrationResult {
+    /** What was upgraded */
+    upgraded: string[];
+    /** What was already up to date */
+    skipped: string[];
+    /** Any errors that occurred (non-fatal) */
+    errors: string[];
+}
+export interface MigratorConfig {
+    projectDir: string;
+    stateDir: string;
+    port: number;
+    hasTelegram: boolean;
+    projectName: string;
+}
+export declare class PostUpdateMigrator {
+    private config;
+    constructor(config: MigratorConfig);
+    /**
+     * Run all post-update migrations. Safe to call multiple times —
+     * each migration is idempotent.
+     */
+    migrate(): MigrationResult;
+    /**
+     * Re-install hooks with the latest templates.
+     * Hooks are generated infrastructure — always overwrite.
+     */
+    private migrateHooks;
+    /**
+     * Patch CLAUDE.md with any new sections that don't exist yet.
+     * Only adds — never modifies or removes existing content.
+     */
+    private migrateClaudeMd;
+    /**
+     * Install any new scripts that don't exist yet.
+     * Never overwrites existing scripts (user may have customized them).
+     */
+    private migrateScripts;
+    private getSessionStartHook;
+    private getDangerousCommandGuard;
+    private getGroundingBeforeMessaging;
+    private getCompactionRecovery;
+    private getTelegramReplyScript;
+    private getHealthWatchdog;
+}
+//# sourceMappingURL=PostUpdateMigrator.d.ts.map

package/dist/core/PostUpdateMigrator.js

@@ -0,0 +1,347 @@
+/**
+ * Post-Update Migrator — the "intelligence download" layer.
+ *
+ * When an agent installs a new version of instar, updating the npm
+ * package only changes the server code. But the agent's local awareness
+ * lives in project files: CLAUDE.md, hooks, scripts.
+ *
+ * This migrator bridges that gap. After every successful update, it:
+ *   1. Re-installs hooks with the latest templates (behavioral upgrades)
+ *   2. Patches CLAUDE.md with any new sections (awareness upgrades)
+ *   3. Installs any new scripts (capability upgrades)
+ *   4. Returns a human-readable migration report
+ *
+ * Design principles:
+ *   - Additive only: never remove or modify existing user customizations
+ *   - Hooks are overwritten (they're generated infrastructure, not user-edited)
+ *   - CLAUDE.md sections are appended only if missing (check by heading)
+ *   - Scripts are installed only if missing (never overwrite user modifications)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class PostUpdateMigrator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Run all post-update migrations. Safe to call multiple times —
+     * each migration is idempotent.
+     */
+    migrate() {
+        const result = {
+            upgraded: [],
+            skipped: [],
+            errors: [],
+        };
+        this.migrateHooks(result);
+        this.migrateClaudeMd(result);
+        this.migrateScripts(result);
+        return result;
+    }
+    /**
+     * Re-install hooks with the latest templates.
+     * Hooks are generated infrastructure — always overwrite.
+     */
+    migrateHooks(result) {
+        const hooksDir = path.join(this.config.stateDir, 'hooks');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        try {
+            // Session start hook — the most important one for self-discovery
+            fs.writeFileSync(path.join(hooksDir, 'session-start.sh'), this.getSessionStartHook(), { mode: 0o755 });
+            result.upgraded.push('hooks/session-start.sh (capability awareness)');
+        }
+        catch (err) {
+            result.errors.push(`session-start.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'dangerous-command-guard.sh'), this.getDangerousCommandGuard(), { mode: 0o755 });
+            result.upgraded.push('hooks/dangerous-command-guard.sh');
+        }
+        catch (err) {
+            result.errors.push(`dangerous-command-guard.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'grounding-before-messaging.sh'), this.getGroundingBeforeMessaging(), { mode: 0o755 });
+            result.upgraded.push('hooks/grounding-before-messaging.sh');
+        }
+        catch (err) {
+            result.errors.push(`grounding-before-messaging.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            fs.writeFileSync(path.join(hooksDir, 'compaction-recovery.sh'), this.getCompactionRecovery(), { mode: 0o755 });
+            result.upgraded.push('hooks/compaction-recovery.sh');
+        }
+        catch (err) {
+            result.errors.push(`compaction-recovery.sh: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Patch CLAUDE.md with any new sections that don't exist yet.
+     * Only adds — never modifies or removes existing content.
+     */
+    migrateClaudeMd(result) {
+        const claudeMdPath = path.join(this.config.projectDir, 'CLAUDE.md');
+        if (!fs.existsSync(claudeMdPath)) {
+            result.skipped.push('CLAUDE.md (not found — will be created on next init)');
+            return;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(claudeMdPath, 'utf-8');
+        }
+        catch (err) {
+            result.errors.push(`CLAUDE.md read: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        let patched = false;
+        const port = this.config.port;
+        // Self-Discovery section
+        if (!content.includes('Self-Discovery') && !content.includes('/capabilities')) {
+            const section = `
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+curl http://localhost:${port}/capabilities
+\`\`\`
+
+This returns your full capability matrix: scripts, hooks, Telegram status, jobs, relationships, and more. It is the source of truth about what you can do. **Never hallucinate about missing capabilities — verify first.**
+`;
+            // Insert before "### How to Build" or "### Building New" if present, otherwise append
+            const insertPoint = content.indexOf('### How to Build New Capabilities');
+            const insertPoint2 = content.indexOf('### Building New Capabilities');
+            const target = insertPoint >= 0 ? insertPoint : (insertPoint2 >= 0 ? insertPoint2 : -1);
+            if (target >= 0) {
+                content = content.slice(0, target) + section + '\n' + content.slice(target);
+            }
+            else {
+                content += '\n' + section;
+            }
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Self-Discovery section');
+        }
+        else {
+            result.skipped.push('CLAUDE.md: Self-Discovery section already present');
+        }
+        // Telegram Relay section — add if Telegram is configured but section is missing
+        if (this.config.hasTelegram && !content.includes('Telegram Relay') && !content.includes('telegram-reply')) {
+            const section = `
+## Telegram Relay
+
+When user input starts with \`[telegram:N]\` (e.g., \`[telegram:26] hello\`), the message came from a user via Telegram topic N. **After responding**, relay your response back:
+
+\`\`\`bash
+cat <<'EOF' | .claude/scripts/telegram-reply.sh N
+Your response text here
+EOF
+\`\`\`
+
+Strip the \`[telegram:N]\` prefix before interpreting the message. Respond naturally, then relay. Only relay your conversational text — not tool output or internal reasoning.
+`;
+            content += '\n' + section;
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Telegram Relay section');
+        }
+        if (patched) {
+            try {
+                fs.writeFileSync(claudeMdPath, content);
+            }
+            catch (err) {
+                result.errors.push(`CLAUDE.md write: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /**
+     * Install any new scripts that don't exist yet.
+     * Never overwrites existing scripts (user may have customized them).
+     */
+    migrateScripts(result) {
+        const scriptsDir = path.join(this.config.projectDir, '.claude', 'scripts');
+        fs.mkdirSync(scriptsDir, { recursive: true });
+        // Telegram reply script — install if Telegram configured and script missing
+        if (this.config.hasTelegram) {
+            const scriptPath = path.join(scriptsDir, 'telegram-reply.sh');
+            if (!fs.existsSync(scriptPath)) {
+                try {
+                    fs.writeFileSync(scriptPath, this.getTelegramReplyScript(), { mode: 0o755 });
+                    result.upgraded.push('scripts/telegram-reply.sh (Telegram outbound relay)');
+                }
+                catch (err) {
+                    result.errors.push(`telegram-reply.sh: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                result.skipped.push('scripts/telegram-reply.sh (already exists)');
+            }
+        }
+        // Health watchdog — install if missing
+        const watchdogPath = path.join(scriptsDir, 'health-watchdog.sh');
+        if (!fs.existsSync(watchdogPath)) {
+            try {
+                fs.writeFileSync(watchdogPath, this.getHealthWatchdog(), { mode: 0o755 });
+                result.upgraded.push('scripts/health-watchdog.sh');
+            }
+            catch (err) {
+                result.errors.push(`health-watchdog.sh: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            result.skipped.push('scripts/health-watchdog.sh (already exists)');
+        }
+    }
+    // ── Hook Templates ─────────────────────────────────────────────────
+    getSessionStartHook() {
+        return `#!/bin/bash
+# Session start hook — injects identity context when a new Claude session begins.
+INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+CONTEXT=""
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  CONTEXT="\${CONTEXT}Your identity file is at .instar/AGENT.md — read it if you need to remember who you are.\\n"
+fi
+if [ -f "$INSTAR_DIR/USER.md" ]; then
+  CONTEXT="\${CONTEXT}Your user context is at .instar/USER.md — read it to know who you're working with.\\n"
+fi
+if [ -f "$INSTAR_DIR/MEMORY.md" ]; then
+  CONTEXT="\${CONTEXT}Your persistent memory is at .instar/MEMORY.md — check it for past learnings.\\n"
+fi
+if [ -d "$INSTAR_DIR/relationships" ]; then
+  REL_COUNT=$(ls -1 "$INSTAR_DIR/relationships"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$REL_COUNT" -gt "0" ]; then
+    CONTEXT="\${CONTEXT}You have \${REL_COUNT} tracked relationships in .instar/relationships/.\\n"
+  fi
+fi
+
+# Self-discovery: check what capabilities are available
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  PORT=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('port', 4040))" 2>/dev/null || echo "4040")
+  HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+  if [ "$HEALTH" = "200" ]; then
+    CONTEXT="\${CONTEXT}Instar server is running on port \${PORT}. Query your capabilities: curl http://localhost:\${PORT}/capabilities\\n"
+    CONTEXT="\${CONTEXT}IMPORTANT: Before claiming you lack a capability, check /capabilities first.\\n"
+  fi
+fi
+
+[ -n "$CONTEXT" ] && echo "$CONTEXT"
+`;
+    }
+    getDangerousCommandGuard() {
+        return `#!/bin/bash
+# Dangerous command guard — blocks destructive operations.
+INPUT="$1"
+for pattern in "rm -rf /" "rm -rf ~" "rm -rf \\." "git push --force" "git push -f" "git reset --hard" "git clean -fd" "DROP TABLE" "DROP DATABASE" "TRUNCATE" "DELETE FROM" "> /dev/sda" "mkfs\\." "dd if=" ":(){:|:&};:"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    echo "BLOCKED: Potentially destructive command detected: $pattern"
+    echo "If you genuinely need to run this, ask the user for explicit confirmation first."
+    exit 2
+  fi
+done
+`;
+    }
+    getGroundingBeforeMessaging() {
+        return `#!/bin/bash
+# Grounding before messaging — Security Through Identity.
+INPUT="$1"
+if echo "$INPUT" | grep -qE "(telegram-reply|send-email|send-message|POST.*/telegram/reply)"; then
+  INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+  if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+    echo "Before sending this message, remember who you are."
+    echo "Re-read .instar/AGENT.md if you haven't recently."
+    echo "Security Through Identity: An agent that knows itself is harder to compromise."
+  fi
+fi
+`;
+    }
+    getCompactionRecovery() {
+        return `#!/bin/bash
+# Compaction recovery — re-injects identity when Claude's context compresses.
+INSTAR_DIR="\${CLAUDE_PROJECT_DIR:-.}/.instar"
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  AGENT_NAME=$(head -5 "$INSTAR_DIR/AGENT.md" | grep -iE "name|I am|My name" | head -1)
+  [ -n "$AGENT_NAME" ] && echo "Identity reminder: $AGENT_NAME"
+  echo "Read .instar/AGENT.md and .instar/MEMORY.md to restore full context."
+fi
+`;
+    }
+    getTelegramReplyScript() {
+        const port = this.config.port;
+        return `#!/bin/bash
+# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
+#
+# Usage:
+#   .claude/scripts/telegram-reply.sh TOPIC_ID "message text"
+#   echo "message text" | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   cat <<'EOF' | .claude/scripts/telegram-reply.sh TOPIC_ID
+#   Multi-line message here
+#   EOF
+
+TOPIC_ID="$1"
+shift
+
+if [ -z "$TOPIC_ID" ]; then
+  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="\${INSTAR_PORT:-${port}}"
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  JSON_MSG="$(printf '%s' "$MSG" | sed 's/\\\\\\\\/\\\\\\\\\\\\\\\\/g; s/"/\\\\\\\\"/g' | sed ':a;N;$!ba;s/\\\\n/\\\\\\\\n/g')"
+  JSON_MSG="\\"$JSON_MSG\\""
+fi
+
+RESPONSE=$(curl -s -w "\\n%{http_code}" -X POST "http://localhost:\${PORT}/telegram/reply/\${TOPIC_ID}" \\
+  -H 'Content-Type: application/json' \\
+  -d "{\\"text\\":\${JSON_MSG}}")
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi
+`;
+    }
+    getHealthWatchdog() {
+        const port = this.config.port;
+        const projectName = this.config.projectName;
+        const escapedProjectDir = this.config.projectDir.replace(/'/g, "'\\''");
+        return `#!/bin/bash
+# health-watchdog.sh — Monitor instar server and auto-recover.
+# Install as cron: */5 * * * * '${path.join(this.config.projectDir, '.claude/scripts/health-watchdog.sh').replace(/'/g, "'\\''")}'
+
+PORT="${port}"
+SERVER_SESSION="${projectName}-server"
+PROJECT_DIR='${escapedProjectDir}'
+TMUX_PATH=$(which tmux 2>/dev/null || echo "/opt/homebrew/bin/tmux")
+
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:\${PORT}/health" 2>/dev/null)
+if [ "$HTTP_CODE" = "200" ]; then exit 0; fi
+
+echo "[\$(date -Iseconds)] Server not responding. Restarting..."
+$TMUX_PATH kill-session -t "=\${SERVER_SESSION}" 2>/dev/null
+sleep 2
+cd "$PROJECT_DIR" && npx instar server start
+echo "[\$(date -Iseconds)] Server restart initiated"
+`;
+    }
+}
+//# sourceMappingURL=PostUpdateMigrator.js.map

package/dist/core/UpdateChecker.d.ts

@@ -17,11 +17,23 @@ export interface RollbackResult {
     restoredVersion: string;
     message: string;
 }
+export interface UpdateCheckerConfig {
+    stateDir: string;
+    /** Required for post-update migrations */
+    projectDir?: string;
+    /** Server port for capability URLs in migrated files */
+    port?: number;
+    /** Whether Telegram is configured */
+    hasTelegram?: boolean;
+    /** Project name for migrated files */
+    projectName?: string;
+}
 export declare class UpdateChecker {
     private stateDir;
     private stateFile;
     private rollbackFile;
-    constructor(stateDir: string);
+    private migratorConfig;
+    constructor(config: string | UpdateCheckerConfig);
     /**
      * Check npm for the latest version, fetch changelog, and compare to installed.
      */

package/dist/core/UpdateChecker.js

@@ -13,16 +13,31 @@
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { refreshHooksAndSettings } from '../commands/init.js';
+import { PostUpdateMigrator } from './PostUpdateMigrator.js';
 const GITHUB_RELEASES_URL = 'https://api.github.com/repos/SageMindAI/instar/releases';
 export class UpdateChecker {
     stateDir;
     stateFile;
     rollbackFile;
-    constructor(stateDir) {
-        this.stateDir = stateDir;
-        this.stateFile = path.join(stateDir, 'state', 'update-check.json');
-        this.rollbackFile = path.join(stateDir, 'state', 'update-rollback.json');
+    migratorConfig;
+    constructor(config) {
+        // Backwards-compatible: accept plain string (stateDir) or config object
+        if (typeof config === 'string') {
+            this.stateDir = config;
+            this.migratorConfig = null;
+        }
+        else {
+            this.stateDir = config.stateDir;
+            this.migratorConfig = config.projectDir ? {
+                projectDir: config.projectDir,
+                stateDir: config.stateDir,
+                port: config.port ?? 4040,
+                hasTelegram: config.hasTelegram ?? false,
+                projectName: config.projectName ?? 'agent',
+            } : null;
+        }
+        this.stateFile = path.join(this.stateDir, 'state', 'update-check.json');
+        this.rollbackFile = path.join(this.stateDir, 'state', 'update-rollback.json');
     }
     /**
      * Check npm for the latest version, fetch changelog, and compare to installed.
@@ -111,13 +126,22 @@ export class UpdateChecker {
         // Save rollback info on successful update
         if (success) {
             this.saveRollbackInfo(previousVersion, newVersion);
-            // Refresh hooks and settings — new versions may include new hooks
+        }
+        // Post-update migration: upgrade hooks, CLAUDE.md, scripts
+        let migrationSummary = '';
+        if (success && this.migratorConfig) {
             try {
-                const projectDir = path.resolve(this.stateDir, '..');
-                refreshHooksAndSettings(projectDir, this.stateDir);
+                const migrator = new PostUpdateMigrator(this.migratorConfig);
+                const migration = migrator.migrate();
+                if (migration.upgraded.length > 0) {
+                    migrationSummary = ` Intelligence download: ${migration.upgraded.length} files upgraded (${migration.upgraded.join(', ')}).`;
+                }
+                if (migration.errors.length > 0) {
+                    migrationSummary += ` Migration warnings: ${migration.errors.join('; ')}.`;
+                }
             }
-            catch {
-                // Non-critical — hooks can be refreshed manually via `instar init`
+            catch (err) {
+                migrationSummary = ` Post-update migration failed: ${err instanceof Error ? err.message : String(err)}.`;
             }
         }
         return {
@@ -125,7 +149,7 @@ export class UpdateChecker {
             previousVersion,
             newVersion,
             message: success
-                ? `Updated from v${previousVersion} to v${newVersion}. Hooks refreshed. ${info.changeSummary || 'Restart to use the new version.'}`
+                ? `Updated from v${previousVersion} to v${newVersion}.${migrationSummary} ${info.changeSummary || 'Restart to use the new version.'}`
                 : `Update command ran but version didn't change (still v${previousVersion}). May need manual intervention.`,
             restartNeeded: success,
             healthCheck: 'skipped', // Can't check health until after restart

package/dist/index.d.ts

@@ -9,7 +9,9 @@ export { RelationshipManager } from './core/RelationshipManager.js';
 export { FeedbackManager } from './core/FeedbackManager.js';
 export { DispatchManager } from './core/DispatchManager.js';
 export { UpdateChecker } from './core/UpdateChecker.js';
-export type { RollbackResult } from './core/UpdateChecker.js';
+export type { RollbackResult, UpdateCheckerConfig } from './core/UpdateChecker.js';
+export { PostUpdateMigrator } from './core/PostUpdateMigrator.js';
+export type { MigrationResult, MigratorConfig } from './core/PostUpdateMigrator.js';
 export { loadConfig, detectTmuxPath, detectClaudePath, detectProjectDir, ensureStateDir } from './core/Config.js';
 export { UserManager } from './users/UserManager.js';
 export { JobScheduler } from './scheduler/JobScheduler.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { RelationshipManager } from './core/RelationshipManager.js';
 export { FeedbackManager } from './core/FeedbackManager.js';
 export { DispatchManager } from './core/DispatchManager.js';
 export { UpdateChecker } from './core/UpdateChecker.js';
+export { PostUpdateMigrator } from './core/PostUpdateMigrator.js';
 export { loadConfig, detectTmuxPath, detectClaudePath, detectProjectDir, ensureStateDir } from './core/Config.js';
 // Users
 export { UserManager } from './users/UserManager.js';

package/dist/scaffold/templates.js

@@ -155,6 +155,16 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 
 **Scripts** — Reusable capabilities in \`.claude/scripts/\`.
 
+### Self-Discovery (Know Before You Claim)
+
+Before EVER saying "I don't have", "I can't", or "this isn't available" — check what actually exists:
+
+\`\`\`bash
+curl http://localhost:${port}/capabilities
+\`\`\`
+
+This returns your full capability matrix: scripts, hooks, Telegram status, jobs, relationships, and more. It is the source of truth about what you can do. **Never hallucinate about missing capabilities — verify first.**
+
 ### Building New Capabilities
 
 When asked for something I can't do yet, I build it:

package/dist/server/routes.js

@@ -7,6 +7,8 @@
 import { Router } from 'express';
 import { execFileSync } from 'node:child_process';
 import { createHash, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 import { rateLimiter } from './middleware.js';
 // Validation patterns for route parameters
 const SESSION_NAME_RE = /^[a-zA-Z0-9_-]{1,200}$/;
@@ -60,6 +62,102 @@ export function createRoutes(ctx) {
             scheduler: schedulerStatus,
         });
     });
+    // ── Capabilities (Self-Discovery) ──────────────────────────────
+    //
+    // Returns a structured self-portrait of what this agent has available.
+    // Agents should query this at session start rather than guessing
+    // about what infrastructure exists.
+    router.get('/capabilities', (_req, res) => {
+        const projectDir = ctx.config.projectDir;
+        const stateDir = ctx.config.stateDir;
+        // Identity files
+        const identityFiles = {
+            'AGENT.md': fs.existsSync(path.join(stateDir, 'AGENT.md')),
+            'USER.md': fs.existsSync(path.join(stateDir, 'USER.md')),
+            'MEMORY.md': fs.existsSync(path.join(stateDir, 'MEMORY.md')),
+        };
+        // Scripts
+        const scriptsDir = path.join(projectDir, '.claude', 'scripts');
+        let scripts = [];
+        if (fs.existsSync(scriptsDir)) {
+            try {
+                scripts = fs.readdirSync(scriptsDir).filter(f => !f.startsWith('.'));
+            }
+            catch { /* permission error, etc. */ }
+        }
+        // Hooks
+        const hooksDir = path.join(stateDir, 'hooks');
+        let hooks = [];
+        if (fs.existsSync(hooksDir)) {
+            try {
+                hooks = fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'));
+            }
+            catch { /* permission error, etc. */ }
+        }
+        // Telegram
+        const hasTelegramConfig = ctx.config.messaging.some(m => m.type === 'telegram' && m.enabled);
+        const hasTelegramReplyScript = scripts.includes('telegram-reply.sh');
+        const telegram = {
+            configured: hasTelegramConfig,
+            replyScript: hasTelegramReplyScript,
+            adapter: !!ctx.telegram,
+            bidirectional: hasTelegramConfig && hasTelegramReplyScript && !!ctx.telegram,
+        };
+        // Jobs
+        let jobCount = 0;
+        let jobSlugs = [];
+        if (ctx.scheduler) {
+            const jobs = ctx.scheduler.getJobs();
+            jobCount = jobs.length;
+            jobSlugs = jobs.map(j => j.slug);
+        }
+        // Relationships
+        const relationshipsDir = ctx.config.relationships?.relationshipsDir;
+        let relationshipCount = 0;
+        if (relationshipsDir && fs.existsSync(relationshipsDir)) {
+            try {
+                relationshipCount = fs.readdirSync(relationshipsDir)
+                    .filter(f => f.endsWith('.json')).length;
+            }
+            catch { /* ignore */ }
+        }
+        // Users
+        let userCount = 0;
+        const usersFile = path.join(stateDir, 'users.json');
+        if (fs.existsSync(usersFile)) {
+            try {
+                const users = JSON.parse(fs.readFileSync(usersFile, 'utf-8'));
+                if (Array.isArray(users))
+                    userCount = users.length;
+            }
+            catch { /* ignore */ }
+        }
+        res.json({
+            project: ctx.config.projectName,
+            version: ctx.config.version || '0.0.0',
+            port: ctx.config.port,
+            identity: identityFiles,
+            scripts,
+            hooks,
+            telegram,
+            scheduler: {
+                enabled: ctx.config.scheduler.enabled,
+                jobCount,
+                jobSlugs,
+            },
+            relationships: {
+                enabled: !!ctx.config.relationships,
+                count: relationshipCount,
+            },
+            feedback: {
+                enabled: !!ctx.config.feedback?.enabled,
+            },
+            users: {
+                count: userCount,
+            },
+            monitoring: ctx.config.monitoring,
+        });
+    });
     // ── Sessions ────────────────────────────────────────────────────
     // Literal routes BEFORE parameterized routes to avoid capture
     router.get('/sessions/tmux', (_req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",