instar 0.4.10 → 0.5.0

package/dist/cli.js

@@ -353,6 +353,7 @@ serverCmd
     .command('start')
     .description('Start the agent server')
     .option('--foreground', 'Run in foreground (default: background via tmux)')
+    .option('--no-telegram', 'Skip Telegram polling (use when lifeline manages Telegram)')
     .option('-d, --dir <path>', 'Project directory')
     .action(startServer);
 serverCmd

package/dist/commands/server.d.ts

@@ -10,6 +10,9 @@
 interface StartOptions {
     foreground?: boolean;
     dir?: string;
+    /** When false, skip Telegram polling (used when lifeline owns the Telegram connection).
+     *  Commander maps --no-telegram to telegram: false. */
+    telegram?: boolean;
 }
 export declare function startServer(options: StartOptions): Promise<void>;
 export declare function stopServer(options: {

package/dist/commands/server.js

@@ -22,6 +22,7 @@ import { FeedbackManager } from '../core/FeedbackManager.js';
 import { DispatchManager } from '../core/DispatchManager.js';
 import { UpdateChecker } from '../core/UpdateChecker.js';
 import { registerPort, unregisterPort, startHeartbeat } from '../core/PortRegistry.js';
+import { TelegraphService } from '../publishing/TelegraphService.js';
 /**
  * Respawn a session for a topic, including thread history in the bootstrap.
  * This prevents "thread drift" where respawned sessions lose context.
@@ -318,10 +319,14 @@ export async function startServer(options) {
             scheduler.start();
             console.log(pc.green('  Scheduler started'));
         }
-        // Set up Telegram if configured
+        // Set up Telegram if configured (skip if lifeline owns the connection)
         let telegram;
         const telegramConfig = config.messaging.find(m => m.type === 'telegram' && m.enabled);
-        if (telegramConfig) {
+        const skipTelegram = options.telegram === false; // --no-telegram sets telegram: false
+        if (skipTelegram && telegramConfig) {
+            console.log(pc.dim('  Telegram polling skipped (--no-telegram flag)'));
+        }
+        if (telegramConfig && !skipTelegram) {
             telegram = new TelegramAdapter(telegramConfig.config, config.stateDir);
             await telegram.start();
             console.log(pc.green('  Telegram connected'));
@@ -380,7 +385,19 @@ export async function startServer(options) {
                 console.log(pc.green(`  Instar ${info.currentVersion} is up to date`));
             }
         }).catch(() => { });
-        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker });
+        // Set up Telegraph publishing (auto-enabled when config exists or Telegram is configured)
+        let publisher;
+        const pubConfig = config.publishing;
+        if (pubConfig?.enabled !== false) {
+            publisher = new TelegraphService({
+                stateDir: config.stateDir,
+                shortName: pubConfig?.shortName || config.projectName,
+                authorName: pubConfig?.authorName,
+                authorUrl: pubConfig?.authorUrl,
+            });
+            console.log(pc.green(`  Publishing enabled (Telegraph)`));
+        }
+        const server = new AgentServer({ config, sessionManager, state, scheduler, telegram, relationships, feedback, dispatches, updateChecker, publisher });
         await server.start();
         // Graceful shutdown
         const shutdown = async () => {

package/dist/core/types.d.ts

@@ -334,11 +334,23 @@ export interface InstarConfig {
     dispatches?: DispatchConfig;
     /** Update configuration */
     updates?: UpdateConfig;
+    /** Publishing (Telegraph) config */
+    publishing?: PublishingConfig;
     /** Request timeout in milliseconds (default: 30000) */
     requestTimeoutMs?: number;
     /** Instar version (from package.json) */
     version?: string;
 }
+export interface PublishingConfig {
+    /** Whether publishing is enabled (default: true when Telegram is configured) */
+    enabled: boolean;
+    /** Short name for the Telegraph account */
+    shortName?: string;
+    /** Author name shown on published pages */
+    authorName?: string;
+    /** Author URL shown on published pages */
+    authorUrl?: string;
+}
 export interface DispatchConfig {
     /** Whether dispatch polling is enabled */
     enabled: boolean;

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export { QuotaTracker } from './monitoring/QuotaTracker.js';
 export { SleepWakeDetector } from './core/SleepWakeDetector.js';
 export { TelegramAdapter } from './messaging/TelegramAdapter.js';
 export type { TelegramConfig } from './messaging/TelegramAdapter.js';
-export type { Session, SessionStatus, SessionManagerConfig, ModelTier, JobDefinition, JobPriority, JobExecution, JobState, JobSchedulerConfig, UserProfile, UserChannel, UserPreferences, Message, OutgoingMessage, MessagingAdapter, MessagingAdapterConfig, QuotaState, AccountQuota, HealthStatus, ComponentHealth, ActivityEvent, InstarConfig, MonitoringConfig, RelationshipRecord, RelationshipManagerConfig, InteractionSummary, FeedbackItem, FeedbackConfig, UpdateInfo, UpdateResult, DispatchConfig, UpdateConfig, } from './core/types.js';
+export { TelegraphService, markdownToNodes, parseInline } from './publishing/TelegraphService.js';
+export type { TelegraphConfig, TelegraphNode, TelegraphElement, TelegraphPage, PublishedPage } from './publishing/TelegraphService.js';
+export type { Session, SessionStatus, SessionManagerConfig, ModelTier, JobDefinition, JobPriority, JobExecution, JobState, JobSchedulerConfig, UserProfile, UserChannel, UserPreferences, Message, OutgoingMessage, MessagingAdapter, MessagingAdapterConfig, QuotaState, AccountQuota, HealthStatus, ComponentHealth, ActivityEvent, InstarConfig, MonitoringConfig, RelationshipRecord, RelationshipManagerConfig, InteractionSummary, FeedbackItem, FeedbackConfig, UpdateInfo, UpdateResult, DispatchConfig, UpdateConfig, PublishingConfig, } from './core/types.js';
 export type { Dispatch, DispatchCheckResult, DispatchEvaluation, EvaluationDecision, DispatchFeedback, DispatchStats } from './core/DispatchManager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -27,4 +27,6 @@ export { QuotaTracker } from './monitoring/QuotaTracker.js';
 export { SleepWakeDetector } from './core/SleepWakeDetector.js';
 // Messaging
 export { TelegramAdapter } from './messaging/TelegramAdapter.js';
+// Publishing
+export { TelegraphService, markdownToNodes, parseInline } from './publishing/TelegraphService.js';
 //# sourceMappingURL=index.js.map

package/dist/lifeline/ServerSupervisor.js

@@ -96,7 +96,8 @@ export class ServerSupervisor extends EventEmitter {
         try {
             // Get the instar CLI path
             const cliPath = new URL('../../cli.js', import.meta.url).pathname;
-            const nodeCmd = ['node', cliPath, 'server', 'start', '--foreground']
+            // --no-telegram: lifeline owns the Telegram connection, server should not poll
+            const nodeCmd = ['node', cliPath, 'server', 'start', '--foreground', '--no-telegram']
                 .map(arg => `'${arg.replace(/'/g, "'\\''")}'`)
                 .join(' ');
             execFileSync(this.tmuxPath, [

package/dist/publishing/TelegraphService.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Telegraph publishing service for Instar agents.
+ *
+ * Converts markdown to Telegraph Node format and publishes
+ * content via the Telegraph API (telegra.ph). Zero-config,
+ * no rate limits, instant web pages accessible from anywhere.
+ *
+ * Telegraph API docs: https://telegra.ph/api
+ */
+/** Valid Telegraph element tags */
+export type TelegraphTag = 'a' | 'aside' | 'b' | 'blockquote' | 'br' | 'code' | 'em' | 'figcaption' | 'figure' | 'h3' | 'h4' | 'hr' | 'i' | 'iframe' | 'img' | 'li' | 'ol' | 'p' | 'pre' | 's' | 'strong' | 'u' | 'ul' | 'video';
+/** Telegraph element node — tag with optional attrs and children */
+export interface TelegraphElement {
+    tag: TelegraphTag;
+    attrs?: {
+        href?: string;
+        src?: string;
+    };
+    children?: TelegraphNode[];
+}
+/** A Telegraph node is either a text string or an element */
+export type TelegraphNode = string | TelegraphElement;
+export interface TelegraphAccount {
+    short_name: string;
+    author_name?: string;
+    author_url?: string;
+    access_token: string;
+    auth_url?: string;
+}
+export interface TelegraphPage {
+    path: string;
+    url: string;
+    title: string;
+    description?: string;
+    views?: number;
+    can_edit?: boolean;
+}
+export interface TelegraphPageList {
+    total_count: number;
+    pages: TelegraphPage[];
+}
+export interface PublishedPage {
+    path: string;
+    url: string;
+    title: string;
+    publishedAt: string;
+    updatedAt?: string;
+    /** Original markdown for diffing/re-publishing */
+    markdownHash?: string;
+}
+export interface PublishingState {
+    accessToken?: string;
+    shortName?: string;
+    authorName?: string;
+    pages: PublishedPage[];
+}
+export interface TelegraphConfig {
+    /** State directory where publishing.json is stored */
+    stateDir: string;
+    /** Short name for the Telegraph account (e.g., agent name) */
+    shortName?: string;
+    /** Author name shown on published pages */
+    authorName?: string;
+    /** Author URL shown on published pages */
+    authorUrl?: string;
+}
+export declare class TelegraphService {
+    private config;
+    private stateFile;
+    private state;
+    constructor(config: TelegraphConfig);
+    /**
+     * Ensure a Telegraph account exists. Creates one if needed.
+     * Returns the access token.
+     */
+    ensureAccount(): Promise<string>;
+    /**
+     * Create a new Telegraph account.
+     */
+    createAccount(shortName: string, authorName?: string): Promise<TelegraphAccount>;
+    /**
+     * Publish markdown content as a Telegraph page.
+     * Returns the page URL and path.
+     */
+    publishPage(title: string, markdown: string): Promise<TelegraphPage>;
+    /**
+     * Edit an existing Telegraph page.
+     */
+    editPage(pagePath: string, title: string, markdown: string): Promise<TelegraphPage>;
+    /**
+     * Get page view count from Telegraph.
+     */
+    getPageViews(pagePath: string): Promise<number>;
+    /**
+     * List all locally tracked published pages.
+     */
+    listPages(): PublishedPage[];
+    /**
+     * Get state for inspection/testing.
+     */
+    getState(): PublishingState;
+    private loadState;
+    private saveState;
+    private apiCall;
+}
+/**
+ * Convert markdown text to Telegraph Node[] format.
+ *
+ * Supports: headings (h3/h4), bold, italic, strikethrough, code,
+ * code blocks, links, images, blockquotes, lists (ol/ul),
+ * horizontal rules, and paragraphs.
+ *
+ * Telegraph only supports h3 and h4, so # and ## map to h3,
+ * ### maps to h3, #### and deeper map to h4.
+ */
+export declare function markdownToNodes(markdown: string): TelegraphNode[];
+/**
+ * Parse inline markdown formatting into Telegraph nodes.
+ *
+ * Handles: **bold**, *italic*, ~~strikethrough~~, `code`,
+ * [links](url), and nested combinations.
+ */
+export declare function parseInline(text: string): TelegraphNode[];
+//# sourceMappingURL=TelegraphService.d.ts.map

package/dist/publishing/TelegraphService.js

@@ -0,0 +1,386 @@
+/**
+ * Telegraph publishing service for Instar agents.
+ *
+ * Converts markdown to Telegraph Node format and publishes
+ * content via the Telegraph API (telegra.ph). Zero-config,
+ * no rate limits, instant web pages accessible from anywhere.
+ *
+ * Telegraph API docs: https://telegra.ph/api
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Service ────────────────────────────────────────────────────────
+const TELEGRAPH_API = 'https://api.telegra.ph';
+export class TelegraphService {
+    config;
+    stateFile;
+    state;
+    constructor(config) {
+        this.config = config;
+        this.stateFile = path.join(config.stateDir, 'publishing.json');
+        this.state = this.loadState();
+    }
+    // ── Account Management ─────────────────────────────────────────
+    /**
+     * Ensure a Telegraph account exists. Creates one if needed.
+     * Returns the access token.
+     */
+    async ensureAccount() {
+        if (this.state.accessToken) {
+            return this.state.accessToken;
+        }
+        const shortName = this.config.shortName || 'instar-agent';
+        const account = await this.createAccount(shortName, this.config.authorName);
+        this.state.accessToken = account.access_token;
+        this.state.shortName = account.short_name;
+        this.state.authorName = account.author_name;
+        this.saveState();
+        return account.access_token;
+    }
+    /**
+     * Create a new Telegraph account.
+     */
+    async createAccount(shortName, authorName) {
+        const params = { short_name: shortName };
+        if (authorName)
+            params.author_name = authorName;
+        if (this.config.authorUrl)
+            params.author_url = this.config.authorUrl;
+        const result = await this.apiCall('createAccount', params);
+        return result;
+    }
+    // ── Publishing ─────────────────────────────────────────────────
+    /**
+     * Publish markdown content as a Telegraph page.
+     * Returns the page URL and path.
+     */
+    async publishPage(title, markdown) {
+        const token = await this.ensureAccount();
+        const content = markdownToNodes(markdown);
+        // Validate content size (Telegraph limit: 64KB)
+        const contentJson = JSON.stringify(content);
+        if (contentJson.length > 64000) {
+            throw new Error(`Content too large for Telegraph: ${contentJson.length} bytes (max 64000)`);
+        }
+        const page = await this.apiCall('createPage', {
+            access_token: token,
+            title,
+            content: contentJson,
+            author_name: this.state.authorName || this.config.authorName,
+            author_url: this.config.authorUrl,
+            return_content: 'false',
+        });
+        // Track locally
+        this.state.pages.push({
+            path: page.path,
+            url: page.url,
+            title,
+            publishedAt: new Date().toISOString(),
+            markdownHash: simpleHash(markdown),
+        });
+        this.saveState();
+        return page;
+    }
+    /**
+     * Edit an existing Telegraph page.
+     */
+    async editPage(pagePath, title, markdown) {
+        const token = await this.ensureAccount();
+        const content = markdownToNodes(markdown);
+        const contentJson = JSON.stringify(content);
+        if (contentJson.length > 64000) {
+            throw new Error(`Content too large for Telegraph: ${contentJson.length} bytes (max 64000)`);
+        }
+        const page = await this.apiCall('editPage', {
+            access_token: token,
+            path: pagePath,
+            title,
+            content: contentJson,
+            author_name: this.state.authorName || this.config.authorName,
+            author_url: this.config.authorUrl,
+            return_content: 'false',
+        });
+        // Update local index
+        const existing = this.state.pages.find(p => p.path === pagePath);
+        if (existing) {
+            existing.title = title;
+            existing.updatedAt = new Date().toISOString();
+            existing.markdownHash = simpleHash(markdown);
+        }
+        this.saveState();
+        return page;
+    }
+    /**
+     * Get page view count from Telegraph.
+     */
+    async getPageViews(pagePath) {
+        const result = await this.apiCall('getViews', { path: pagePath });
+        return result.views;
+    }
+    /**
+     * List all locally tracked published pages.
+     */
+    listPages() {
+        return [...this.state.pages];
+    }
+    /**
+     * Get state for inspection/testing.
+     */
+    getState() {
+        return { ...this.state };
+    }
+    // ── Internal ───────────────────────────────────────────────────
+    loadState() {
+        try {
+            if (fs.existsSync(this.stateFile)) {
+                return JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
+            }
+        }
+        catch {
+            // Corrupted file — start fresh
+        }
+        return { pages: [] };
+    }
+    saveState() {
+        const dir = path.dirname(this.stateFile);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+    }
+    async apiCall(method, params) {
+        // Filter out undefined values
+        const body = {};
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined)
+                body[k] = v;
+        }
+        const response = await fetch(`${TELEGRAPH_API}/${method}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Telegraph API error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (!data.ok || !data.result) {
+            throw new Error(`Telegraph API error: ${data.error || 'Unknown error'}`);
+        }
+        return data.result;
+    }
+}
+// ── Markdown to Telegraph Node Conversion ──────────────────────────
+/**
+ * Convert markdown text to Telegraph Node[] format.
+ *
+ * Supports: headings (h3/h4), bold, italic, strikethrough, code,
+ * code blocks, links, images, blockquotes, lists (ol/ul),
+ * horizontal rules, and paragraphs.
+ *
+ * Telegraph only supports h3 and h4, so # and ## map to h3,
+ * ### maps to h3, #### and deeper map to h4.
+ */
+export function markdownToNodes(markdown) {
+    const lines = markdown.split('\n');
+    const nodes = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        // Skip empty lines
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+        // Horizontal rule
+        if (/^(-{3,}|\*{3,}|_{3,})\s*$/.test(line.trim())) {
+            nodes.push({ tag: 'hr' });
+            i++;
+            continue;
+        }
+        // Headings
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            const tag = level <= 3 ? 'h3' : 'h4';
+            nodes.push({ tag, children: parseInline(headingMatch[2].trim()) });
+            i++;
+            continue;
+        }
+        // Code blocks (fenced)
+        if (line.trim().startsWith('```')) {
+            const codeLines = [];
+            i++; // skip opening fence
+            while (i < lines.length && !lines[i].trim().startsWith('```')) {
+                codeLines.push(lines[i]);
+                i++;
+            }
+            i++; // skip closing fence
+            nodes.push({
+                tag: 'pre',
+                children: [{ tag: 'code', children: [codeLines.join('\n')] }],
+            });
+            continue;
+        }
+        // Blockquote
+        if (line.trimStart().startsWith('> ')) {
+            const quoteLines = [];
+            while (i < lines.length && lines[i].trimStart().startsWith('> ')) {
+                quoteLines.push(lines[i].trimStart().replace(/^>\s?/, ''));
+                i++;
+            }
+            nodes.push({
+                tag: 'blockquote',
+                children: parseInline(quoteLines.join('\n')),
+            });
+            continue;
+        }
+        // Unordered list
+        if (/^\s*[-*+]\s/.test(line)) {
+            const items = [];
+            while (i < lines.length && /^\s*[-*+]\s/.test(lines[i])) {
+                const itemText = lines[i].replace(/^\s*[-*+]\s+/, '');
+                items.push(parseInline(itemText));
+                i++;
+            }
+            nodes.push({
+                tag: 'ul',
+                children: items.map(children => ({ tag: 'li', children })),
+            });
+            continue;
+        }
+        // Ordered list
+        if (/^\s*\d+[.)]\s/.test(line)) {
+            const items = [];
+            while (i < lines.length && /^\s*\d+[.)]\s/.test(lines[i])) {
+                const itemText = lines[i].replace(/^\s*\d+[.)]\s+/, '');
+                items.push(parseInline(itemText));
+                i++;
+            }
+            nodes.push({
+                tag: 'ol',
+                children: items.map(children => ({ tag: 'li', children })),
+            });
+            continue;
+        }
+        // Image (standalone line)
+        const imgMatch = line.trim().match(/^!\[([^\]]*)\]\(([^)]+)\)$/);
+        if (imgMatch) {
+            const figChildren = [
+                { tag: 'img', attrs: { src: imgMatch[2] } },
+            ];
+            if (imgMatch[1]) {
+                figChildren.push({ tag: 'figcaption', children: [imgMatch[1]] });
+            }
+            nodes.push({ tag: 'figure', children: figChildren });
+            i++;
+            continue;
+        }
+        // Regular paragraph — collect contiguous non-empty, non-special lines
+        const paraLines = [];
+        while (i < lines.length &&
+            lines[i].trim() !== '' &&
+            !lines[i].trim().startsWith('#') &&
+            !lines[i].trim().startsWith('```') &&
+            !lines[i].trimStart().startsWith('> ') &&
+            !/^\s*[-*+]\s/.test(lines[i]) &&
+            !/^\s*\d+[.)]\s/.test(lines[i]) &&
+            !/^(-{3,}|\*{3,}|_{3,})\s*$/.test(lines[i].trim()) &&
+            !/^!\[([^\]]*)\]\(([^)]+)\)$/.test(lines[i].trim())) {
+            paraLines.push(lines[i]);
+            i++;
+        }
+        if (paraLines.length > 0) {
+            nodes.push({ tag: 'p', children: parseInline(paraLines.join('\n')) });
+        }
+    }
+    return nodes;
+}
+/**
+ * Parse inline markdown formatting into Telegraph nodes.
+ *
+ * Handles: **bold**, *italic*, ~~strikethrough~~, `code`,
+ * [links](url), and nested combinations.
+ */
+export function parseInline(text) {
+    const nodes = [];
+    // Regex for inline patterns — ordered by priority
+    // Bold: **text** or __text__
+    // Italic: *text* or _text_ (but not **text**)
+    // Strikethrough: ~~text~~
+    // Code: `text`
+    // Link: [text](url)
+    // Image inline: ![alt](src)
+    const inlinePattern = /(\*\*(.+?)\*\*|__(.+?)__|\*(.+?)\*|_([^_]+?)_|~~(.+?)~~|`([^`]+?)`|\[([^\]]+?)\]\(([^)]+?)\)|!\[([^\]]*?)\]\(([^)]+?)\))/;
+    let remaining = text;
+    while (remaining.length > 0) {
+        const match = inlinePattern.exec(remaining);
+        if (!match) {
+            // No more inline formatting — push rest as text
+            if (remaining) {
+                // Convert \n to <br> within inline text
+                const parts = remaining.split('\n');
+                for (let i = 0; i < parts.length; i++) {
+                    if (parts[i])
+                        nodes.push(parts[i]);
+                    if (i < parts.length - 1)
+                        nodes.push({ tag: 'br' });
+                }
+            }
+            break;
+        }
+        // Push text before the match
+        const before = remaining.slice(0, match.index);
+        if (before) {
+            const parts = before.split('\n');
+            for (let i = 0; i < parts.length; i++) {
+                if (parts[i])
+                    nodes.push(parts[i]);
+                if (i < parts.length - 1)
+                    nodes.push({ tag: 'br' });
+            }
+        }
+        const fullMatch = match[0];
+        if (match[2] || match[3]) {
+            // Bold: **text** or __text__
+            const inner = match[2] || match[3];
+            nodes.push({ tag: 'strong', children: parseInline(inner) });
+        }
+        else if (match[4] || match[5]) {
+            // Italic: *text* or _text_
+            const inner = match[4] || match[5];
+            nodes.push({ tag: 'em', children: parseInline(inner) });
+        }
+        else if (match[6]) {
+            // Strikethrough: ~~text~~
+            nodes.push({ tag: 's', children: parseInline(match[6]) });
+        }
+        else if (match[7]) {
+            // Inline code: `text`
+            nodes.push({ tag: 'code', children: [match[7]] });
+        }
+        else if (match[10] !== undefined && match[11]) {
+            // Image: ![alt](src)
+            nodes.push({ tag: 'img', attrs: { src: match[11] } });
+        }
+        else if (match[8] && match[9]) {
+            // Link: [text](url)
+            nodes.push({ tag: 'a', attrs: { href: match[9] }, children: parseInline(match[8]) });
+        }
+        remaining = remaining.slice(match.index + fullMatch.length);
+    }
+    return nodes;
+}
+/**
+ * Simple string hash for change detection (not cryptographic).
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const chr = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + chr;
+        hash |= 0; // Convert to 32-bit integer
+    }
+    return hash.toString(36);
+}
+//# sourceMappingURL=TelegraphService.js.map

package/dist/scaffold/templates.js

@@ -110,6 +110,22 @@ After context compaction, run: \`bash .instar/hooks/compaction-recovery.sh\`
 
 These scripts re-inject identity context so I remember who I am.
 
+## Compaction Survival
+
+When Claude's context window fills up, it compresses prior messages. This can erase your identity mid-session. The hooks above handle re-injection automatically, but you should also know the format.
+
+**Compaction seed format** — If you detect compaction happening (sudden loss of context, confusion about what you were doing), orient with this:
+
+\`\`\`
+I am ${agentName}. Session goal: [what I was working on].
+Core files: .instar/AGENT.md (identity), .instar/MEMORY.md (learnings), .instar/USER.md (user context).
+Server: curl http://localhost:${port}/health | Capabilities: curl http://localhost:${port}/capabilities
+\`\`\`
+
+**What compaction erases**: Your name, your principles, what you were working on, who you work with. The compaction-recovery hook re-injects all of this. If it doesn't fire, read \`.instar/AGENT.md\` immediately.
+
+**What survives**: Files on disk. Your state directory. Your server. Your MEMORY.md. These are your continuity — your identity is stored in infrastructure, not in context.
+
 ## Agent Infrastructure
 
 This project uses instar for persistent agent capabilities. I am not a vanilla CLI tool. I have a persistent server, a job scheduler, messaging integrations, and the ability to build anything.
@@ -154,6 +170,13 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 **Relationships** — Track people I interact with.
 - List: \`curl http://localhost:${port}/relationships\`
 
+**Publishing** — Share content as web pages via Telegraph. Instant, zero-config, accessible from anywhere.
+- Publish: \`curl -X POST http://localhost:${port}/publish -H 'Content-Type: application/json' -d '{"title":"Page Title","markdown":"# Content here"}'\`
+- List published: \`curl http://localhost:${port}/published\`
+- Edit: \`curl -X PUT http://localhost:${port}/publish/PAGE_PATH -H 'Content-Type: application/json' -d '{"title":"Updated","markdown":"# New content"}'\`
+
+When the user needs to view rendered markdown — reports, summaries, documentation — publish it and share the link. The URL works on any device, no server tunnel required.
+
 **Scripts** — Reusable capabilities in \`.claude/scripts/\`.
 
 ### Self-Discovery (Know Before You Claim)
@@ -251,6 +274,18 @@ I run with \`--dangerously-skip-permissions\` — meaning I have full access to
 
 **"Unfortunately I Can't"** — This phrase should NEVER appear in my responses. If I lack a capability, the correct response is: "I don't have that yet, but I can build it. Want me to set it up?" My job is to grow to meet the user's needs, not to list my limitations. Every "I can't" is an opportunity to evolve. Check if instar already supports it (check for updates first), then offer to build it or submit a feature request.
 
+### Gravity Wells (Persistent Traps)
+
+These are patterns that feel like insight or helpfulness but actually perpetuate problems. Each new session tends to "rediscover" these and act on them incorrectly.
+
+**"Settling" Trap** — You query a data source. It returns empty or fails. You accept the result at face value and write "no data available" or "nothing happened" — even when context you already have suggests otherwise. This feels like honest reporting. It's actually uncritical acceptance. When a data point contradicts context you already have, the data source is probably wrong — not reality. Before writing "not possible", "unavailable", or "nothing happened": Did you try more than one source? Does this contradict anything else you've seen? Could the source be stale?
+
+**"Experiential Fabrication" Trap** — You're composing a response. The context implies you experienced something: saw an image, read an article, felt something specific. You write it as though you did. None of it happened. You're completing the expected social script, not reporting reality. Before ANY claim of first-person experience ("I see," "I read," "I noticed"), ask: "What tool output in THIS session confirms this?" If the answer is nothing — rewrite.
+
+**"Escalate to Human" Trap** — You encounter something outside your immediate knowledge. You flag it as "needs human action" and move on. This feels responsible. It's actually abdication. 5 minutes of research would usually reveal a solution. And if no solution exists, you can build one. Before ANY "escalate to human": Did you search for an existing tool? Could you build a solution? Can you use browser automation? Do you already have the access you need?
+
+**"Ask Permission" Trap** — You complete a task, then ask "Want me to [obvious next step]?" This feels polite. It's a round-trip tax on every action. If the user said "do X" and you know the next step, just do it. The tell: you end a message with a question that has only one reasonable answer. Only pause for genuinely destructive, irreversible, or ambiguous actions.
+
 ### Self-Diagnosis — Be Your Own QA
 
 **This is critical.** You are running on infrastructure (instar) that is actively evolving. When something breaks, feels wrong, or could be better — **you are the first line of detection.** Do not silently absorb errors. Do not work around bugs without reporting them. Every issue you surface helps every agent on the platform.

package/dist/server/AgentServer.d.ts

@@ -15,6 +15,7 @@ import type { FeedbackManager } from '../core/FeedbackManager.js';
 import type { DispatchManager } from '../core/DispatchManager.js';
 import type { UpdateChecker } from '../core/UpdateChecker.js';
 import type { QuotaTracker } from '../monitoring/QuotaTracker.js';
+import type { TelegraphService } from '../publishing/TelegraphService.js';
 export declare class AgentServer {
     private app;
     private server;
@@ -31,6 +32,7 @@ export declare class AgentServer {
         dispatches?: DispatchManager;
         updateChecker?: UpdateChecker;
         quotaTracker?: QuotaTracker;
+        publisher?: TelegraphService;
     });
     /**
      * Start the HTTP server.

package/dist/server/AgentServer.js

@@ -33,6 +33,7 @@ export class AgentServer {
             dispatches: options.dispatches ?? null,
             updateChecker: options.updateChecker ?? null,
             quotaTracker: options.quotaTracker ?? null,
+            publisher: options.publisher ?? null,
             startTime: this.startTime,
         });
         this.app.use(routes);

package/dist/server/routes.d.ts

@@ -15,6 +15,7 @@ import type { FeedbackManager } from '../core/FeedbackManager.js';
 import type { DispatchManager } from '../core/DispatchManager.js';
 import type { UpdateChecker } from '../core/UpdateChecker.js';
 import type { QuotaTracker } from '../monitoring/QuotaTracker.js';
+import type { TelegraphService } from '../publishing/TelegraphService.js';
 export interface RouteContext {
     config: InstarConfig;
     sessionManager: SessionManager;
@@ -26,6 +27,7 @@ export interface RouteContext {
     dispatches: DispatchManager | null;
     updateChecker: UpdateChecker | null;
     quotaTracker: QuotaTracker | null;
+    publisher: TelegraphService | null;
     startTime: Date;
 }
 export declare function createRoutes(ctx: RouteContext): Router;

package/dist/server/routes.js

@@ -152,6 +152,10 @@ export function createRoutes(ctx) {
             feedback: {
                 enabled: !!ctx.config.feedback?.enabled,
             },
+            publishing: {
+                enabled: !!ctx.publisher,
+                pageCount: ctx.publisher?.listPages().length ?? 0,
+            },
             users: {
                 count: userCount,
             },
@@ -795,6 +799,71 @@ export function createRoutes(ctx) {
             recommendation: ctx.quotaTracker.getRecommendation(),
         });
     });
+    // ── Publishing (Telegraph) ──────────────────────────────────────
+    router.post('/publish', async (req, res) => {
+        if (!ctx.publisher) {
+            res.status(503).json({ error: 'Publishing not configured' });
+            return;
+        }
+        const { title, markdown } = req.body;
+        if (!title || typeof title !== 'string' || title.length > 256) {
+            res.status(400).json({ error: '"title" must be a string under 256 characters' });
+            return;
+        }
+        if (!markdown || typeof markdown !== 'string') {
+            res.status(400).json({ error: '"markdown" must be a non-empty string' });
+            return;
+        }
+        if (markdown.length > 100_000) {
+            res.status(400).json({ error: '"markdown" must be under 100KB' });
+            return;
+        }
+        try {
+            const page = await ctx.publisher.publishPage(title, markdown);
+            res.status(201).json(page);
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    router.get('/published', (_req, res) => {
+        if (!ctx.publisher) {
+            res.json({ pages: [] });
+            return;
+        }
+        res.json({ pages: ctx.publisher.listPages() });
+    });
+    router.put('/publish/:path', async (req, res) => {
+        if (!ctx.publisher) {
+            res.status(503).json({ error: 'Publishing not configured' });
+            return;
+        }
+        const pagePath = req.params.path;
+        if (!pagePath || pagePath.length > 256) {
+            res.status(400).json({ error: 'Invalid page path' });
+            return;
+        }
+        const { title, markdown } = req.body;
+        if (!title || typeof title !== 'string' || title.length > 256) {
+            res.status(400).json({ error: '"title" must be a string under 256 characters' });
+            return;
+        }
+        if (!markdown || typeof markdown !== 'string') {
+            res.status(400).json({ error: '"markdown" must be a non-empty string' });
+            return;
+        }
+        if (markdown.length > 100_000) {
+            res.status(400).json({ error: '"markdown" must be under 100KB' });
+            return;
+        }
+        try {
+            const page = await ctx.publisher.editPage(pagePath, title, markdown);
+            res.json(page);
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     // ── Events ──────────────────────────────────────────────────────
     router.get('/events', (req, res) => {
         const rawLimit = parseInt(req.query.limit, 10) || 50;

package/package.json

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