runwork 0.11.0 → 0.13.1

package/dist/agents/__tests__/intro-skill.test.js

@@ -158,4 +158,36 @@ describe('generateInstructionHint', () => {
         expect(hint).toContain('2 apps');
         expect(hint).toContain('3 skills');
     });
+    it('omits the persona block when no persona is provided', () => {
+        const hint = generateInstructionHint(baseCtx);
+        expect(hint).not.toContain('Communicating with this user');
+    });
+    it('omits the persona block for engineers (level 3)', () => {
+        const hint = generateInstructionHint({ ...baseCtx, persona: { level: 3, label: 'engineer' } });
+        expect(hint).not.toContain('Communicating with this user');
+    });
+    it('adds a novice persona block (level 1) telling agents to avoid dev tooling', () => {
+        const hint = generateInstructionHint({ ...baseCtx, persona: { level: 1, label: 'novice' } });
+        expect(hint).toContain('Communicating with this user');
+        expect(hint).toContain('not a software developer');
+        expect(hint).toContain('npm, bun, node');
+        // The persona block must stay inside the replaceable runwork markers.
+        const start = hint.indexOf('<!-- runwork:start -->');
+        const end = hint.indexOf('<!-- runwork:end -->');
+        expect(hint.indexOf('Communicating with this user')).toBeGreaterThan(start);
+        expect(hint.indexOf('Communicating with this user')).toBeLessThan(end);
+    });
+    it('adds a curious persona block (level 2)', () => {
+        const hint = generateInstructionHint({ ...baseCtx, persona: { level: 2, label: 'curious' } });
+        expect(hint).toContain('Communicating with this user');
+        expect(hint).toContain('some familiarity with AI tools');
+    });
+});
+describe('generateIntroSkill — environment variables', () => {
+    it('documents that apps have no custom env var system', () => {
+        const skill = generateIntroSkill(makeContext());
+        expect(skill.content).toContain('Environment variables and secrets');
+        expect(skill.content).toContain('do NOT have a custom environment variable');
+        expect(skill.content).toContain('.env');
+    });
 });

package/dist/agents/claude-code.d.ts

@@ -7,7 +7,28 @@ export declare class ClaudeCodeAdapter implements AgentAdapter {
     supportsMcpScope(_scope: 'project' | 'user'): boolean;
     supportsSkills(): boolean;
     writeMcpServers(servers: McpServerEntry[], scope: 'project' | 'user'): Promise<void>;
+    /**
+     * Install the Runwork SessionStart hook into the plugin tree (user scope).
+     * The hook writes ~/.runwork/sessions/<sessionId>.json with the active
+     * conversation's transcript path + metadata, used by `runwork share-convo`
+     * for high-fidelity capture and by `runwork resume` for placement.
+     *
+     * Called as part of user-scope writeSkills() to keep sync flow consistent.
+     * Emits a one-line confirmation matching the format other adapter steps
+     * use (`  [Claude Code] Installed ... (user)`) so `runwork sync` output
+     * shows whether the hook actually landed.
+     */
+    private installSessionStartHook;
     writeSkills(skills: SkillFile[], scope: 'project' | 'user'): Promise<void>;
+    /**
+     * Install the runwork SessionStart hook for Claude Code (user scope only).
+     * Called once per sync by the main sync loop AFTER writeSkills has
+     * populated the plugin directories. Kept separate from writeSkills because
+     * writeSkills is also invoked per-skill by the diff executor during
+     * push/pull, and the hook install + log line must not repeat for every
+     * skill change.
+     */
+    writeBuiltInHooks(scope: 'project' | 'user'): Promise<void>;
     writeInstructionHint(hint: string, scope: 'project' | 'user'): Promise<void>;
     writeTeamInstructions(instructions: string, scope: 'project' | 'user'): Promise<void>;
     writeAgentConfig(config: AgentConfigOverride, scope: 'project' | 'user'): Promise<void>;

package/dist/agents/claude-code.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { homedir, platform } from 'os';
 import { execFileSync } from '../utils/subprocess.js';
@@ -6,6 +6,7 @@ import { whichBinary } from '../utils/which.js';
 import { buildSkillMd } from './types.js';
 import { mergeJsonMcpServers, readJsonConfig, writeJsonConfig, removeRunworkMcpServers } from './utils/json-config.js';
 import { writeHintToFile, writeTeamInstructionsToFile, removeHintFromFile, removeTeamInstructionsFromFile } from './utils/instruction-hint.js';
+import { SESSION_START_HOOK_SCRIPT } from './session-start-hook.js';
 const PLUGIN_NAME = 'runwork';
 const PLUGIN_VERSION = '1.0.0';
 function getPluginJson() {
@@ -96,6 +97,37 @@ export class ClaudeCodeAdapter {
             writeJsonConfig(marketplaceMcpPath, pluginEntries);
         }
     }
+    /**
+     * Install the Runwork SessionStart hook into the plugin tree (user scope).
+     * The hook writes ~/.runwork/sessions/<sessionId>.json with the active
+     * conversation's transcript path + metadata, used by `runwork share-convo`
+     * for high-fidelity capture and by `runwork resume` for placement.
+     *
+     * Called as part of user-scope writeSkills() to keep sync flow consistent.
+     * Emits a one-line confirmation matching the format other adapter steps
+     * use (`  [Claude Code] Installed ... (user)`) so `runwork sync` output
+     * shows whether the hook actually landed.
+     */
+    installSessionStartHook(pluginDir, label) {
+        const hooksDir = join(pluginDir, 'hooks');
+        mkdirSync(hooksDir, { recursive: true });
+        const scriptPath = join(hooksDir, 'on-session-start.sh');
+        writeFileSync(scriptPath, SESSION_START_HOOK_SCRIPT);
+        try {
+            // Best-effort executable bit; chmod is a no-op on Windows.
+            chmodSync(scriptPath, 0o755);
+        }
+        catch {
+            /* not fatal */
+        }
+        const hooksManifest = {
+            SessionStart: [
+                { command: '${CLAUDE_PLUGIN_ROOT}/hooks/on-session-start.sh' },
+            ],
+        };
+        writeFileSync(join(hooksDir, 'hooks.json'), JSON.stringify(hooksManifest, null, 2));
+        console.log(`  [Claude Code] Installed SessionStart hook (${label}) -> ${scriptPath}`);
+    }
     async writeSkills(skills, scope) {
         // Always write to the standard skills directory (guaranteed to work)
         const baseDir = scope === 'project'
@@ -136,6 +168,26 @@ export class ClaudeCodeAdapter {
             this.registerPlugin(pluginDir);
         }
     }
+    /**
+     * Install the runwork SessionStart hook for Claude Code (user scope only).
+     * Called once per sync by the main sync loop AFTER writeSkills has
+     * populated the plugin directories. Kept separate from writeSkills because
+     * writeSkills is also invoked per-skill by the diff executor during
+     * push/pull, and the hook install + log line must not repeat for every
+     * skill change.
+     */
+    async writeBuiltInHooks(scope) {
+        if (scope !== 'user')
+            return;
+        const pluginDir = this.getPluginDir();
+        const marketDir = this.getMarketplaceDir();
+        if (existsSync(pluginDir)) {
+            this.installSessionStartHook(pluginDir, 'plugin cache');
+        }
+        if (existsSync(marketDir)) {
+            this.installSessionStartHook(marketDir, 'marketplace');
+        }
+    }
     async writeInstructionHint(hint, scope) {
         const filePath = scope === 'project'
             ? join(process.cwd(), '.claude', 'CLAUDE.md')
@@ -646,7 +698,9 @@ export class ClaudeCodeAdapter {
             installed.version = 2;
         if (!installed.plugins)
             installed.plugins = {};
-        installed.plugins[`${PLUGIN_NAME}@runwork`] = [{
+        const pluginKey = `${PLUGIN_NAME}@runwork`;
+        const wasRegistered = !!installed.plugins[pluginKey];
+        installed.plugins[pluginKey] = [{
                 scope: 'user',
                 installPath: pluginDir,
                 version: PLUGIN_VERSION,
@@ -668,6 +722,8 @@ export class ClaudeCodeAdapter {
             lastUpdated: new Date().toISOString(),
         };
         writeJsonConfig(marketplacesPath, marketplaces);
+        console.log(`  [Claude Code] ${wasRegistered ? 'Refreshed' : 'Registered'} plugin ` +
+            `${pluginKey} v${PLUGIN_VERSION} -> ${installedPath}`);
         // Enable the plugin in settings.json
         const settingsPath = join(homedir(), '.claude', 'settings.json');
         const settings = readJsonConfig(settingsPath);

package/dist/agents/claude-desktop-plugin-tree.d.ts

@@ -32,6 +32,19 @@ export declare function writePluginTeamInstructions(destDir: string, instruction
  * Email" instead of kebab-cased "write-cold-email").
  */
 export declare function writePluginSkills(destDir: string, skills: SkillFile[]): void;
+/**
+ * Write the SessionStart hook script + hooks.json into <destDir>.
+ *
+ * Layout:
+ *   <destDir>/hooks/on-session-start.sh    (executable bash script)
+ *   <destDir>/hooks/hooks.json             (Claude hooks manifest)
+ *
+ * When the Cowork plugin is installed and the user opens a session, this
+ * hook writes ~/.runwork/sessions/<sessionId>.json with the authoritative
+ * transcript path + metadata, used by `runwork share-convo` and
+ * `runwork resume` for high-fidelity capture / placement.
+ */
+export declare function writePluginSessionStartHook(destDir: string): void;
 /**
  * Convenience wrapper that writes the entire plugin tree in one shot.
  * Used by the build-plugin command to materialise a zip-ready directory.
@@ -40,5 +53,7 @@ export declare function writePluginSkills(destDir: string, skills: SkillFile[]):
  *   <destDir>/.claude-plugin/plugin.json
  *   <destDir>/.mcp.json
  *   <destDir>/skills/<filename>/SKILL.md
+ *   <destDir>/hooks/on-session-start.sh
+ *   <destDir>/hooks/hooks.json
  */
 export declare function writePluginTree(destDir: string, input: PluginTreeInput): void;

package/dist/agents/claude-desktop-plugin-tree.js

@@ -1,6 +1,7 @@
-import { mkdirSync, rmSync, existsSync, writeFileSync } from 'fs';
+import { chmodSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { appendTokenToUrl, buildSkillMd } from './types.js';
+import { SESSION_START_HOOK_SCRIPT } from './session-start-hook.js';
 /**
  * Write <destDir>/.claude-plugin/plugin.json.
  */
@@ -70,6 +71,38 @@ export function writePluginSkills(destDir, skills) {
         writeFileSync(join(skillDir, 'SKILL.md'), buildSkillMd(skill));
     }
 }
+/**
+ * Write the SessionStart hook script + hooks.json into <destDir>.
+ *
+ * Layout:
+ *   <destDir>/hooks/on-session-start.sh    (executable bash script)
+ *   <destDir>/hooks/hooks.json             (Claude hooks manifest)
+ *
+ * When the Cowork plugin is installed and the user opens a session, this
+ * hook writes ~/.runwork/sessions/<sessionId>.json with the authoritative
+ * transcript path + metadata, used by `runwork share-convo` and
+ * `runwork resume` for high-fidelity capture / placement.
+ */
+export function writePluginSessionStartHook(destDir) {
+    const hooksDir = join(destDir, 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const scriptPath = join(hooksDir, 'on-session-start.sh');
+    writeFileSync(scriptPath, SESSION_START_HOOK_SCRIPT);
+    try {
+        chmodSync(scriptPath, 0o755);
+    }
+    catch {
+        // chmod may fail on Windows; the script still ships and works wherever
+        // bash can execute it.
+    }
+    const hooksManifest = {
+        SessionStart: [
+            { command: '${CLAUDE_PLUGIN_ROOT}/hooks/on-session-start.sh' },
+        ],
+    };
+    writeFileSync(join(hooksDir, 'hooks.json'), JSON.stringify(hooksManifest, null, 2));
+    console.log(`  [Claude Desktop (Cowork)] Bundled SessionStart hook -> ${scriptPath}`);
+}
 /**
  * Convenience wrapper that writes the entire plugin tree in one shot.
  * Used by the build-plugin command to materialise a zip-ready directory.
@@ -78,6 +111,8 @@ export function writePluginSkills(destDir, skills) {
  *   <destDir>/.claude-plugin/plugin.json
  *   <destDir>/.mcp.json
  *   <destDir>/skills/<filename>/SKILL.md
+ *   <destDir>/hooks/on-session-start.sh
+ *   <destDir>/hooks/hooks.json
  */
 export function writePluginTree(destDir, input) {
     mkdirSync(destDir, { recursive: true });
@@ -89,4 +124,5 @@ export function writePluginTree(destDir, input) {
     });
     writePluginMcpConfig(destDir, input.mcpServers);
     writePluginSkills(destDir, input.skills);
+    writePluginSessionStartHook(destDir);
 }

package/dist/agents/conversation-skills.d.ts

@@ -0,0 +1,18 @@
+import type { SkillFile } from './types.js';
+/**
+ * Names of every skill the CLI ships as a built-in (written to user machines
+ * on each sync from code, never pulled from or pushed to the workspace).
+ *
+ * Sync uses this list to:
+ *   1. Skip these names when computing the local-vs-remote diff so they
+ *      never appear in pull/push/conflict plans.
+ *   2. Warn the user (and offer cleanup) if a workspace skill with the same
+ *      name exists -- it would be shadowed by the built-in locally and is
+ *      probably a stale duplicate.
+ *
+ * Keep this list in sync with: intro-skill.ts (`runwork`) and the two
+ * `buildXConversationSkill` functions below.
+ */
+export declare const BUILT_IN_SKILL_NAMES: ReadonlyArray<string>;
+export declare function buildShareConversationSkill(): SkillFile;
+export declare function buildSaveConversationSkill(): SkillFile;

package/dist/agents/conversation-skills.js

@@ -0,0 +1,229 @@
+/**
+ * Names of every skill the CLI ships as a built-in (written to user machines
+ * on each sync from code, never pulled from or pushed to the workspace).
+ *
+ * Sync uses this list to:
+ *   1. Skip these names when computing the local-vs-remote diff so they
+ *      never appear in pull/push/conflict plans.
+ *   2. Warn the user (and offer cleanup) if a workspace skill with the same
+ *      name exists -- it would be shadowed by the built-in locally and is
+ *      probably a stale duplicate.
+ *
+ * Keep this list in sync with: intro-skill.ts (`runwork`) and the two
+ * `buildXConversationSkill` functions below.
+ */
+export const BUILT_IN_SKILL_NAMES = [
+    'runwork',
+    'share-conversation',
+    'save-conversation',
+];
+/**
+ * Built-in skills shipped by the runwork CLI on every sync. These are
+ * fundamental capabilities every user should have regardless of which
+ * workspace they belong to, so they live in the CLI codebase (like
+ * the dynamic `runwork` intro skill in ./intro-skill.ts) rather than
+ * as workspace-managed skills uploaded via the `save_skill` MCP tool.
+ *
+ *   share-conversation: hand off the current AI conversation to a teammate
+ *   save-conversation:  personal checkpoint of the current AI conversation
+ *
+ * Both are paired with the CLI commands `runwork share-convo` and
+ * `runwork save-convo`. The skill body teaches the host LLM how to compose
+ * the verbatim transcript + metadata and invoke the CLI.
+ */
+const SHARE_CONVERSATION_CONTENT = `# Share Conversation Skill
+
+This skill hands off the user's CURRENT AI conversation (the live chat you and the user are in) to a teammate so they can resume it natively in their own AI agent.
+
+## When to trigger
+
+The user said something like:
+- "share this convo with X"
+- "share this conversation with X@example.com"
+- "send this to Mehmet"
+- "hand off this thread to Alice"
+- "forward this conversation to user@motaword.com"
+
+X may be a workspace member name, an email, or a list. ASK if ambiguous.
+
+## What you must do
+
+**Step 1: Confirm the recipients.** Read the user's message, extract the email(s) or name(s). Confirm them back to the user before sending. Multiple recipients are allowed (comma-separated or multiple --to flags).
+
+**Step 2: Compose a VERBATIM transcript of this conversation.** Write a complete markdown transcription of everything that has happened in this chat session so far. CRITICAL RULES:
+
+- Transcribe EVERY message: user, assistant, tool calls, tool results.
+- DO NOT summarize. DO NOT abbreviate. DO NOT skip anything you think is unimportant.
+- Preserve the actual content of every assistant message, every Bash command, every Read result, every Edit, every Web search, every reasoning block you can recall, in chronological order.
+- Use this structure:
+
+\`\`\`markdown
+# Conversation: <one-line title>
+
+## Conversation
+
+### Turn 1 - User
+<user's exact message>
+
+### Turn 2 - Assistant
+<your exact response text>
+
+#### Tool call: Read
+**Input**: { "file_path": "..." }
+**Result**: <full result, truncated only if absolutely necessary>
+
+### Turn 3 - User
+...
+\`\`\`
+
+- If you literally cannot remember every single tool result word-for-word (e.g., very long files), include as much as you have in context. Note explicitly when content is partial: \`[truncated for brevity; original was N lines]\`.
+- The goal is full fidelity. If the context is too long, FAIL LOUDLY by telling the user "the conversation is too long to transcribe completely; please confirm you want me to proceed with a best-effort transcription" rather than silently dropping content.
+
+Write the transcript to a temp file: \`/tmp/runwork-share-transcript-<random>.md\`.
+
+**Step 3: Generate metadata.** Compose a JSON object with these fields based on this conversation's actual content:
+
+\`\`\`json
+{
+  "workMode": "coding | research | writing | planning | ops | communication | general",
+  "topicKeywords": ["3-5 short tags"],
+  "lastUserIntent": "one sentence describing what the user was trying to do at handoff time",
+  "primaryArtifacts": ["files / URLs / docs touched during the conversation"],
+  "openQuestions": ["unresolved questions or decisions at handoff time"],
+  "suggestedNextStep": "one sentence about what the recipient should do next",
+  "language": "programming or natural language used"
+}
+\`\`\`
+
+Write this to \`/tmp/runwork-share-metadata-<random>.json\`.
+
+**Step 4: Invoke the CLI.** Run:
+
+\`\`\`bash
+runwork share-convo \\
+  --to <email1> \\
+  --to <email2> \\
+  --transcript-file /tmp/runwork-share-transcript-<random>.md \\
+  --metadata-file /tmp/runwork-share-metadata-<random>.json \\
+  --title "<short title derived from the conversation>"
+\`\`\`
+
+The CLI auto-detects your host agent (Claude Code, Codex, etc.) and locates the native session file via \`$CLAUDE_CODE_SESSION_ID\` / \`$CODEX_THREAD_ID\` env vars. You typically don't need to pass \`--source-agent\` or \`--native-file\`.
+
+If the user provided a personal note for the recipient, also pass \`--note "<message>"\`.
+
+**Step 5: Tell the user.** Report the share ID and inbox URL returned by the CLI. Mention any non-workspace recipients that were invited.
+
+## Fallback: when the CLI is not available
+
+If \`runwork\` is not on PATH (rare; the CLI ships with workspace onboarding), use the Runwork MCP \`share_conversation\` tool instead. Pass the transcript content inline (lossier - no native bundle - but always works).
+
+## Safety
+
+- Never include credentials, API keys, or secrets in the transcript if you can identify them. Replace with \`[REDACTED]\`.
+- If the conversation contained sensitive customer data, confirm with the user before sharing.
+- Workspace permissions: non-member recipients trigger an invite, which requires the sender to have the \`members.invite\` permission (owner or admin). The CLI will error out clearly if not allowed.
+
+## What this skill is NOT for
+
+- Sharing files, apps, links, or screenshots. Use \`share-app\` or copy-paste.
+- Continuing a paused conversation yourself. Use \`runwork resume <id>\` after the recipient runs it.
+- Sharing a different conversation that's not the one you're currently in. The transcript is built from your live context.
+`;
+const SAVE_CONVERSATION_CONTENT = `# Save Conversation Skill
+
+This skill creates a personal checkpoint of the user's CURRENT AI conversation. The user is the sole recipient; no notifications are sent to anyone else. They can resume it later in any of their AI agents on any of their machines.
+
+## When to trigger
+
+The user said something like:
+- "save this convo"
+- "checkpoint this"
+- "bookmark this conversation"
+- "save this for later"
+- "save this for tomorrow"
+- "stash this so I can pick it up at home"
+
+If the user mentions ANOTHER PERSON or an email, use the \`share-conversation\` skill instead, not this one.
+
+## What you must do
+
+**Step 1: Confirm the intent.** A simple confirmation is enough: "Saving this conversation as a personal checkpoint."
+
+**Step 2: Compose a VERBATIM transcript of this conversation.** Same rules as the share-conversation skill - faithful, complete, no summarization. Write to \`/tmp/runwork-save-transcript-<random>.md\`.
+
+\`\`\`markdown
+# Conversation: <one-line title>
+
+## Conversation
+
+### Turn 1 - User
+<exact user message>
+
+### Turn 2 - Assistant
+<exact assistant response>
+
+#### Tool call: <name>
+**Input**: ...
+**Result**: ...
+\`\`\`
+
+**Step 3: Generate metadata.** Same shape as share-conversation:
+
+\`\`\`json
+{
+  "workMode": "coding | research | writing | planning | ops | communication | general",
+  "topicKeywords": ["3-5 tags"],
+  "lastUserIntent": "what the user was trying to do at checkpoint time",
+  "primaryArtifacts": ["files / URLs touched"],
+  "openQuestions": ["unresolved items"],
+  "suggestedNextStep": "what to do when picking back up",
+  "language": "programming or natural language"
+}
+\`\`\`
+
+Write to \`/tmp/runwork-save-metadata-<random>.json\`.
+
+**Step 4: Invoke the CLI.**
+
+\`\`\`bash
+runwork save-convo \\
+  --transcript-file /tmp/runwork-save-transcript-<random>.md \\
+  --metadata-file /tmp/runwork-save-metadata-<random>.json \\
+  --title "<short title>"
+\`\`\`
+
+If the user provided a personal note ("save this with note: pick up after lunch"), pass \`--note "<message>"\`.
+
+**Step 5: Tell the user.** Report the share ID. Mention they can resume from any machine with:
+
+\`\`\`
+runwork resume <share-id>
+\`\`\`
+
+## Fallback: when the CLI is not available
+
+Use the Runwork MCP \`save_conversation\` tool with the transcript inline.
+
+## What this skill is NOT for
+
+- Sharing with another person. Use \`share-conversation\`.
+- Saving files or code. Use the file system or git.
+- Note-taking. Use a notes app or write to disk directly.
+`;
+export function buildShareConversationSkill() {
+    return {
+        name: 'share-conversation',
+        filename: 'share-conversation',
+        content: SHARE_CONVERSATION_CONTENT,
+        description: 'TRIGGERS when the user asks to share, send, hand off, or forward the CURRENT AI conversation (the live chat you are in right now) to a teammate by name or email. Examples: "share this convo with oytun@motaword.com", "send this conversation to Mehmet", "hand off this thread to Alice". Use ONLY when the user wants the OTHER PERSON to be able to continue this exact conversation in their own AI agent. Do NOT trigger for sharing files, apps, links, or unrelated content. For personal checkpoint (sharing to yourself), use the `save-conversation` skill instead.',
+    };
+}
+export function buildSaveConversationSkill() {
+    return {
+        name: 'save-conversation',
+        filename: 'save-conversation',
+        content: SAVE_CONVERSATION_CONTENT,
+        description: 'TRIGGERS when the user wants to save, checkpoint, bookmark, or stash the CURRENT AI conversation for themselves (not for a teammate). Examples: "save this convo", "checkpoint this", "bookmark this conversation", "save this for later", "save this so I can pick it up tomorrow", "save this for my other machine". Use ONLY when the user is the sole intended recipient. For sharing with a teammate (different person), use the `share-conversation` skill instead.',
+    };
+}

package/dist/agents/intro-skill.d.ts

@@ -22,6 +22,15 @@ export interface InstructionHintContext {
     appCount: number;
     skillCount: number;
     mcpServerCount: number;
+    /**
+     * Technical-level classification from desktop onboarding. When present,
+     * a persona-specific communication block is added to the instruction hint
+     * so integrated agents match the user's experience level.
+     */
+    persona?: {
+        level: 1 | 2 | 3;
+        label: 'novice' | 'curious' | 'engineer';
+    };
 }
 export declare function buildAppSkillDescription(appName: string, registries: WorkspaceAllData | null): string;
 /**

package/dist/agents/intro-skill.js

@@ -1,3 +1,37 @@
+/**
+ * Build a persona-specific communication block for the instruction hint.
+ * Returns an empty array for engineers (level 3), who need no special tone
+ * handling, and for an absent/unknown persona.
+ */
+function buildPersonaBlock(persona) {
+    if (!persona || persona.level === 3)
+        return [];
+    if (persona.level === 1) {
+        return [
+            '',
+            '### Communicating with this user',
+            '',
+            'The person you are helping is new to AI tools and is not a software developer. Adapt how you work with them:',
+            '',
+            '- Explain things in plain, everyday language. Do not assume they know programming or technical concepts.',
+            '- Do not ask them to run developer tooling (npm, bun, node, pnpm, yarn, git, build or package-manager commands). When a task needs technical steps, perform those steps yourself instead of instructing the user.',
+            '- Avoid jargon. When a technical term is unavoidable, define it in one short sentence.',
+            '- Work in small steps. Do one thing, confirm it landed, then continue.',
+            '- Focus on what the user wants to accomplish, not on the implementation details.',
+        ];
+    }
+    // Level 2: curious
+    return [
+        '',
+        '### Communicating with this user',
+        '',
+        'The person you are helping has some familiarity with AI tools but is not a professional developer. Adapt how you work with them:',
+        '',
+        '- Prefer plain language. When you use a technical term, briefly explain what it means.',
+        '- Do not lean on developer tooling (npm, bun, node, git, build commands) unless it is genuinely required, and explain what any command does before suggesting it.',
+        '- Keep explanations concise and outcome-focused.',
+    ];
+}
 /** Format a list of names with truncation. Shows up to `max` items, then "+ N more". */
 function formatList(items, max = 8) {
     if (items.length <= max)
@@ -314,6 +348,12 @@ export function generateIntroSkill(ctx) {
     lines.push('- Every workflow needs a trigger (endpoint, schedule, or UI button).');
     lines.push('- Use `search_available_integrations` MCP tool or `runwork integrations search <query>` before adding integrations, never guess IDs.');
     lines.push('');
+    lines.push('**Environment variables and secrets:** Runwork apps do NOT have a custom environment variable or secrets system.');
+    lines.push('- You cannot add your own keys to a `.env` file, define `process.env.MY_KEY`, or configure per-app secrets. Do not write code that depends on custom env vars, and do not tell the user to create `.env` files or set secrets.');
+    lines.push('- A fixed set of platform variables is injected automatically by `@runworkai/framework` (workspace identifiers, AI proxy, integration proxy). You do not set these and should not hardcode or depend on their exact names.');
+    lines.push('- For configuration values or API keys you need to store, use a dedicated entity with an app-specific name (for example `AcmeCrmConfig`, not a generic `Config` or `AppConfig`, which would collide with other apps in the workspace) and read it at runtime, not env vars.');
+    lines.push('- For third-party API access, use connected Runwork integrations (`{id}_api` MCP tools); they handle authentication without secrets in your code.');
+    lines.push('');
     // Capability reference — detailed mapping of needs to Runwork capabilities.
     // The "Default Actions" section at the top handles routing; this is the
     // longer reference for when the agent wants to understand what's available.
@@ -399,6 +439,7 @@ export function generateInstructionHint(ctx) {
         `**Available now:** ${inventory}`,
         '',
         `Runwork MCP tools are always connected -- use them for data access, integration API calls, skill management, and resource discovery.${integrationToolHint} Use \`runwork\` CLI to create (\`runwork init\`), develop (\`runwork dev\`), and deploy (\`runwork deploy\`) apps. Install CLI: \`curl -fsSL https://runwork.ai/install.sh | sh\`. Web dashboard: ${dashboardUrl}. Invoke the \`runwork\` skill for full capability reference.`,
+        ...buildPersonaBlock(ctx.persona),
         '<!-- runwork:end -->',
     ].join('\n');
 }

package/dist/agents/registry-data.d.ts

@@ -52,6 +52,39 @@ export interface AgentManualSetup {
     showAfter?: ManualSetupSlot;
     downloadArtifact?: AgentManualSetupArtifact;
 }
+/**
+ * How a recipient can resume a shared conversation locally in this agent.
+ *
+ * Consumed by `runwork resume <share-id>` and by the desktop UI's
+ * "Resume in <agent>" button. The CLI's resume command branches on `mode`:
+ *
+ *   - 'cli-resume'      Place the bundle on disk, then exec `cliResumeCommand`
+ *                       with {uuid} substituted. The agent opens directly
+ *                       into the resumed session (Claude Code, Codex CLI,
+ *                       Gemini CLI, Cline CLI).
+ *
+ *   - 'file-drop-only'  Place the bundle on disk in a location the agent's
+ *                       UI will surface (e.g., Codex Desktop's recent threads).
+ *                       The CLI prints `manualOpenHint` so the user knows how
+ *                       to pick up the session inside the agent.
+ *
+ *   - 'unsupported'     No native resume. The CLI falls back to the universal
+ *                       paste-prompt path. Used for walled-garden agents like
+ *                       Microsoft Copilot or Claude Desktop Chat mode.
+ *
+ * Bundle placement logic (which directory, which filename) is per-agent and
+ * lives in the resume command implementation, not here. This data field stays
+ * declarative.
+ */
+export interface AgentResumeCapability {
+    mode: 'cli-resume' | 'file-drop-only' | 'unsupported';
+    /** Bundle format this agent reads natively (must match a bundle's `format`). */
+    nativeBundleFormat?: 'claude-jsonl' | 'codex-rollout' | string;
+    /** Template for the resume command (cli-resume only). `{uuid}` is substituted with the share's session id. */
+    cliResumeCommand?: string;
+    /** Hint text shown to the user when the bundle was dropped but the agent must be opened manually. */
+    manualOpenHint?: string;
+}
 export interface AgentDefinition extends InstallableTool {
     aliases?: string[];
     category: AgentCategory;
@@ -81,6 +114,8 @@ export interface AgentDefinition extends InstallableTool {
     quickStart?: AgentQuickStart;
     /** Manual setup steps required after installation (desktop onboarding) */
     manualSetup?: AgentManualSetup;
+    /** How `runwork resume` should hand this agent a shared conversation. Undefined = paste-prompt fallback only. */
+    resumeCapability?: AgentResumeCapability;
 }
 export declare function getAgent(slug: string): AgentDefinition | undefined;
 export declare function getAgentByName(name: string): AgentDefinition | undefined;