runwork 0.6.2 → 0.8.2

package/dist/agents/claude-desktop.js

@@ -1,10 +1,21 @@
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { homedir, platform } from 'os';
-import { buildSkillMd } from './types.js';
-import { mergeJsonMcpServers, readJsonConfig, writeJsonConfig } from './utils/json-config.js';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir, platform, tmpdir } from 'os';
+import { mergeJsonMcpServers, readJsonConfig, writeJsonConfig, removeRunworkMcpServers } from './utils/json-config.js';
+import { createZipFromDir } from '../utils/zip.js';
+import { writePluginMcpConfig, writePluginMetadata, writePluginSkills, writePluginTeamInstructions, writePluginTree, } from './claude-desktop-plugin-tree.js';
 const PLUGIN_NAME = 'runwork';
 const PLUGIN_VERSION = '1.0.0';
+const PLUGIN_DESCRIPTION = 'Skills and tools from your Runwork workspace';
+const PLUGIN_AUTHOR_NAME = 'Runwork';
+function getPluginMetadata() {
+    return {
+        pluginName: PLUGIN_NAME,
+        pluginVersion: PLUGIN_VERSION,
+        description: PLUGIN_DESCRIPTION,
+        authorName: PLUGIN_AUTHOR_NAME,
+    };
+}
 function getMcpConfigPath() {
     const os = platform();
     if (os === 'darwin') {
@@ -26,50 +37,101 @@ function getCoworkBaseDir() {
     return join(homedir(), '.config', 'Claude', 'local-agent-mode-sessions');
 }
 /**
- * Find the cowork_plugins directory by discovering the session/org ID structure.
- * Path: local-agent-mode-sessions/<session-id>/<org-id>/cowork_plugins/
+ * Walk all `local-agent-mode-sessions/<session>/<org>/` directories and
+ * invoke `visit` for each. Stops and returns the first non-null result.
  */
-function findCoworkPluginsDir() {
+function walkOrgDirs(visit) {
     const baseDir = getCoworkBaseDir();
     if (!existsSync(baseDir))
         return null;
     try {
-        const entries = readdirSync(baseDir).filter(d => !d.startsWith('.') && d !== 'skills-plugin');
-        for (const sessionId of entries) {
+        const sessionDirs = readdirSync(baseDir).filter(d => !d.startsWith('.') && d !== 'skills-plugin');
+        for (const sessionId of sessionDirs) {
             const sessionPath = join(baseDir, sessionId);
-            const orgDirs = readdirSync(sessionPath).filter(d => !d.startsWith('.'));
+            let orgDirs;
+            try {
+                orgDirs = readdirSync(sessionPath).filter(d => !d.startsWith('.'));
+            }
+            catch {
+                continue;
+            }
             for (const orgId of orgDirs) {
-                const pluginsDir = join(sessionPath, orgId, 'cowork_plugins');
-                if (existsSync(join(pluginsDir, 'installed_plugins.json'))) {
-                    return pluginsDir;
-                }
+                const orgDir = join(sessionPath, orgId);
+                const result = visit(orgDir);
+                if (result !== null)
+                    return result;
             }
         }
     }
-    catch { /* ignore */ }
+    catch {
+        /* ignore */
+    }
     return null;
 }
-function getPluginJson() {
-    return {
-        name: PLUGIN_NAME,
-        version: PLUGIN_VERSION,
-        description: 'Skills and tools from your Runwork workspace',
-        author: { name: 'Runwork' },
-    };
+/**
+ * Find the cowork_plugins directory by discovering the session/org ID structure.
+ * Path: local-agent-mode-sessions/<session-id>/<org-id>/cowork_plugins/
+ */
+function findCoworkPluginsDir() {
+    return walkOrgDirs((orgDir) => {
+        const pluginsDir = join(orgDir, 'cowork_plugins');
+        return existsSync(join(pluginsDir, 'installed_plugins.json')) ? pluginsDir : null;
+    });
+}
+/**
+ * Look for a plugin named `pluginName` in any `rpm/manifest.json`. These
+ * entries are created by Claude Desktop when the user uploads a plugin zip
+ * through Customize > Create plugin > Upload plugin. If found, sync should
+ * update the plugin content files inside the rpm plugin directory instead
+ * of writing to the legacy `cowork_plugins/` layout.
+ *
+ * We never modify `rpm/manifest.json` itself — Claude Desktop owns that
+ * registry and assigns the plugin id we read from it here.
+ */
+export function findRpmPluginByName(pluginName) {
+    return walkOrgDirs((orgDir) => {
+        const manifestPath = join(orgDir, 'rpm', 'manifest.json');
+        if (!existsSync(manifestPath))
+            return null;
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            const entry = manifest.plugins?.find((p) => p.name === pluginName);
+            if (!entry?.id)
+                return null;
+            return {
+                pluginPath: join(orgDir, 'rpm', entry.id),
+                orgDir,
+            };
+        }
+        catch {
+            return null;
+        }
+    });
 }
 function getMarketplaceJson() {
     return {
         name: 'runwork',
-        owner: { name: 'Runwork' },
+        owner: { name: PLUGIN_AUTHOR_NAME },
         plugins: [
             {
                 name: PLUGIN_NAME,
                 source: `./plugins/${PLUGIN_NAME}`,
-                description: 'Skills and tools from your Runwork workspace',
+                description: PLUGIN_DESCRIPTION,
             },
         ],
     };
 }
+function getCoworkSettingsPath(pluginsDir) {
+    return join(dirname(pluginsDir), 'cowork_settings.json');
+}
+function setCoworkPluginEnabled(pluginsDir, enabled) {
+    const settingsPath = getCoworkSettingsPath(pluginsDir);
+    const settings = readJsonConfig(settingsPath);
+    const enabledPlugins = (settings.enabledPlugins ?? {});
+    enabledPlugins[`${PLUGIN_NAME}@runwork`] = enabled;
+    settings.enabledPlugins = enabledPlugins;
+    writeJsonConfig(settingsPath, settings);
+}
 export class ClaudeDesktopAdapter {
     name = 'Claude Desktop (Cowork)';
     slug = 'claude-desktop';
@@ -86,8 +148,14 @@ export class ClaudeDesktopAdapter {
         return true;
     }
     async writeMcpServers(servers, _scope) {
-        // Claude Desktop Cowork mode only supports stdio transport.
-        // Use mcp-remote as a bridge for HTTP/SSE servers.
+        // Claude Desktop has two MCP transport paths:
+        // 1. claude_desktop_config.json with mcp-remote (stdio bridge): for chat mode
+        // 2. .mcp.json inside the plugin directory (native HTTP): for cowork mode connectors
+        //
+        // For cowork connectors, embed the auth token in the URL query string.
+        // This lets Claude Desktop connect without requiring the user to go through
+        // an OAuth flow or manually click "Connect" in the Connectors UI.
+        // Write to claude_desktop_config.json via mcp-remote (chat mode fallback)
         const entries = {};
         for (const s of servers) {
             const args = ['mcp-remote', s.url];
@@ -100,49 +168,47 @@ export class ClaudeDesktopAdapter {
             };
         }
         mergeJsonMcpServers(getMcpConfigPath(), entries, 'mcpServers');
-        // Also write .mcp.json inside the Cowork plugin directory
+        // Prefer rpm/plugin_<id>/ when the user has uploaded our zip through
+        // Claude Desktop's Customize > Create plugin > Upload plugin flow.
+        const rpm = findRpmPluginByName(PLUGIN_NAME);
+        if (rpm) {
+            writePluginMcpConfig(rpm.pluginPath, servers);
+            return;
+        }
+        // Fall back to the legacy cowork_plugins layout (cache + marketplace).
         const pluginsDir = findCoworkPluginsDir();
         if (pluginsDir) {
             const cacheDir = join(pluginsDir, 'cache', 'runwork', PLUGIN_NAME, PLUGIN_VERSION);
             const marketDir = join(pluginsDir, 'marketplaces', 'runwork', 'plugins', PLUGIN_NAME);
-            const pluginEntries = {};
-            for (const s of servers) {
-                pluginEntries[s.name] = {
-                    type: 'http',
-                    url: s.url,
-                    ...(s.headers ? { headers: s.headers } : {}),
-                    ...(s.description ? { description: s.description } : {}),
-                };
-            }
             for (const dir of [cacheDir, marketDir]) {
-                mkdirSync(dir, { recursive: true });
-                writeJsonConfig(join(dir, '.mcp.json'), pluginEntries);
+                writePluginMcpConfig(dir, servers);
             }
         }
     }
     async writeSkills(skills, _scope) {
+        // Prefer rpm/plugin_<id>/ when the user has uploaded our zip through
+        // Claude Desktop's Customize > Create plugin > Upload plugin flow.
+        // Claude Desktop owns rpm/manifest.json (registration, enablement),
+        // so we only refresh the plugin content files.
+        const rpm = findRpmPluginByName(PLUGIN_NAME);
+        if (rpm) {
+            writePluginMetadata(rpm.pluginPath, getPluginMetadata());
+            writePluginSkills(rpm.pluginPath, skills);
+            return;
+        }
         const pluginsDir = findCoworkPluginsDir();
         if (!pluginsDir) {
             console.warn('  [Claude Desktop] Cowork plugins directory not found. Open Claude Desktop at least once first.');
             return;
         }
-        // Write to both cache (installed copy) and marketplaces (source)
+        // Fall back to legacy cowork_plugins layout: write to both cache
+        // (installed copy) and marketplaces (source).
         const cacheDir = join(pluginsDir, 'cache', 'runwork', PLUGIN_NAME, PLUGIN_VERSION);
         const marketRoot = join(pluginsDir, 'marketplaces', 'runwork');
         const marketDir = join(marketRoot, 'plugins', PLUGIN_NAME);
-        // Create plugin.json in both locations
         for (const dir of [cacheDir, marketDir]) {
-            const pluginJsonDir = join(dir, '.claude-plugin');
-            mkdirSync(pluginJsonDir, { recursive: true });
-            writeFileSync(join(pluginJsonDir, 'plugin.json'), JSON.stringify(getPluginJson(), null, 2));
-        }
-        // Write skill files to both locations
-        for (const skill of skills) {
-            for (const dir of [cacheDir, marketDir]) {
-                const skillDir = join(dir, 'skills', skill.name);
-                mkdirSync(skillDir, { recursive: true });
-                writeFileSync(join(skillDir, 'SKILL.md'), buildSkillMd(skill));
-            }
+            writePluginMetadata(dir, getPluginMetadata());
+            writePluginSkills(dir, skills);
         }
         // Register in installed_plugins.json
         const installedPath = join(pluginsDir, 'installed_plugins.json');
@@ -172,25 +238,55 @@ export class ClaudeDesktopAdapter {
             lastUpdated: new Date().toISOString(),
         };
         writeJsonConfig(marketplacesPath, marketplaces);
+        // Sync should recover a previously disabled plugin so it shows up in Customize.
+        setCoworkPluginEnabled(pluginsDir, true);
     }
     async writeInstructionHint(_hint, _scope) {
         // Claude Desktop/Cowork uses project instructions within the app UI, not files.
         // The plugin system handles skill discovery.
     }
+    async buildPluginZip(skills, mcpServers, teamInstructions, outputPath) {
+        // Materialise the plugin tree into a temp dir, zip it, then clean up.
+        // Uses the same writePluginTree + writePluginTeamInstructions helpers
+        // the sync path uses so the on-disk layout is byte-identical whether
+        // the user installs via upload or sync.
+        const stagingRoot = mkdtempSync(join(tmpdir(), 'runwork-plugin-'));
+        const pluginStagingDir = join(stagingRoot, PLUGIN_NAME);
+        try {
+            writePluginTree(pluginStagingDir, {
+                ...getPluginMetadata(),
+                skills,
+                mcpServers,
+            });
+            if (teamInstructions) {
+                writePluginTeamInstructions(pluginStagingDir, teamInstructions);
+            }
+            createZipFromDir(pluginStagingDir, outputPath);
+        }
+        finally {
+            try {
+                rmSync(stagingRoot, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
     async writeTeamInstructions(instructions, _scope) {
-        // Write team instructions as a skill in the CoWork plugin system.
+        // Write team instructions as a skill in the Cowork plugin system.
         // This makes them available to Claude Desktop sessions via the plugin.
+        // Prefer an rpm upload location when present, fall back to the legacy
+        // cowork_plugins cache + marketplace layout.
+        const rpm = findRpmPluginByName(PLUGIN_NAME);
+        if (rpm) {
+            writePluginTeamInstructions(rpm.pluginPath, instructions);
+            return;
+        }
         const pluginsDir = findCoworkPluginsDir();
         if (!pluginsDir)
             return;
-        const skillContent = `---\nname: runwork-team-instructions\ndescription: Team instructions from your Runwork workspace. Always follow these guidelines.\n---\n\n${instructions}`;
-        // Write to both cache and marketplace locations
-        const cacheDir = join(pluginsDir, 'cache', 'runwork', PLUGIN_NAME, PLUGIN_VERSION, 'skills', 'runwork-team-instructions');
-        const marketDir = join(pluginsDir, 'marketplaces', 'runwork', 'plugins', PLUGIN_NAME, 'skills', 'runwork-team-instructions');
-        for (const dir of [cacheDir, marketDir]) {
-            mkdirSync(dir, { recursive: true });
-            writeFileSync(join(dir, 'SKILL.md'), skillContent);
-        }
+        writePluginTeamInstructions(join(pluginsDir, 'cache', 'runwork', PLUGIN_NAME, PLUGIN_VERSION), instructions);
+        writePluginTeamInstructions(join(pluginsDir, 'marketplaces', 'runwork', 'plugins', PLUGIN_NAME), instructions);
     }
     // ── Agent config (limited to preferences) ──────────────────────────
     async writeAgentConfig(config, _scope) {
@@ -224,6 +320,87 @@ export class ClaudeDesktopAdapter {
         }
         writeFileSync(configPath, JSON.stringify(desktopConfig, null, 2));
     }
+    // ── Cleanup (uninstall) ────────────────────────────────────────────
+    async cleanup(_scope, _manifest) {
+        // 1. Remove MCP entries from claude_desktop_config.json
+        removeRunworkMcpServers(getMcpConfigPath(), 'mcpServers');
+        // 2. Remove the uploaded rpm plugin if the user installed via
+        //    Customize > Create plugin > Upload plugin. We delete both the
+        //    plugin directory and the manifest entry so Claude Desktop does
+        //    not show a stale Runwork plugin after uninstall.
+        const rpm = findRpmPluginByName(PLUGIN_NAME);
+        if (rpm) {
+            if (existsSync(rpm.pluginPath)) {
+                try {
+                    rmSync(rpm.pluginPath, { recursive: true, force: true });
+                }
+                catch { /* best-effort */ }
+            }
+            const manifestPath = join(rpm.orgDir, 'rpm', 'manifest.json');
+            if (existsSync(manifestPath)) {
+                try {
+                    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                    if (Array.isArray(manifest.plugins)) {
+                        manifest.plugins = manifest.plugins.filter((p) => p.name !== PLUGIN_NAME);
+                        manifest.lastUpdated = Date.now();
+                        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+                    }
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        // 3. Remove Cowork plugin directories and registration
+        const pluginsDir = findCoworkPluginsDir();
+        if (pluginsDir) {
+            // Remove cache/runwork and marketplaces/runwork directories
+            const cacheRunwork = join(pluginsDir, 'cache', 'runwork');
+            const marketRunwork = join(pluginsDir, 'marketplaces', 'runwork');
+            for (const dir of [cacheRunwork, marketRunwork]) {
+                if (existsSync(dir)) {
+                    try {
+                        rmSync(dir, { recursive: true, force: true });
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            // Remove from installed_plugins.json
+            const installedPath = join(pluginsDir, 'installed_plugins.json');
+            if (existsSync(installedPath)) {
+                try {
+                    const installed = readJsonConfig(installedPath);
+                    if (installed.plugins) {
+                        delete installed.plugins[`${PLUGIN_NAME}@runwork`];
+                        writeJsonConfig(installedPath, installed);
+                    }
+                }
+                catch { /* best-effort */ }
+            }
+            // Remove from known_marketplaces.json
+            const marketplacesPath = join(pluginsDir, 'known_marketplaces.json');
+            if (existsSync(marketplacesPath)) {
+                try {
+                    const marketplaces = readJsonConfig(marketplacesPath);
+                    delete marketplaces['runwork'];
+                    writeJsonConfig(marketplacesPath, marketplaces);
+                }
+                catch { /* best-effort */ }
+            }
+            // Remove the enable flag so cleanup fully unregisters the plugin.
+            const coworkSettingsPath = getCoworkSettingsPath(pluginsDir);
+            if (existsSync(coworkSettingsPath)) {
+                try {
+                    const settings = readJsonConfig(coworkSettingsPath);
+                    const enabledPlugins = settings.enabledPlugins;
+                    if (enabledPlugins && typeof enabledPlugins === 'object' && !Array.isArray(enabledPlugins)) {
+                        delete enabledPlugins[`${PLUGIN_NAME}@runwork`];
+                        settings.enabledPlugins = enabledPlugins;
+                        writeJsonConfig(coworkSettingsPath, settings);
+                    }
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
     // ── Usage stats (passive, best-effort) ─────────────────────────────
     async readUsageStats(lastSyncAt) {
         try {

package/dist/agents/cline.d.ts

@@ -1,7 +1,8 @@
-import type { AgentAdapter, AgentConfigOverride, McpServerEntry, SkillFile } from './types.js';
+import type { AgentAdapter, AgentConfigOverride, CleanupManifest, McpServerEntry, SkillFile } from './types.js';
 export declare class ClineAdapter implements AgentAdapter {
     name: string;
     slug: string;
+    mcpProvidesSkills: boolean;
     detect(): Promise<boolean>;
     supportsMcpScope(scope: 'project' | 'user'): boolean;
     supportsSkills(): boolean;
@@ -10,4 +11,5 @@ export declare class ClineAdapter implements AgentAdapter {
     writeInstructionHint(hint: string, scope: 'project' | 'user'): Promise<void>;
     writeTeamInstructions(instructions: string, scope: 'project' | 'user'): Promise<void>;
     writeAgentConfig(config: AgentConfigOverride, scope: 'project' | 'user'): Promise<void>;
+    cleanup(scope: 'project' | 'user', manifest?: CleanupManifest): Promise<void>;
 }

package/dist/agents/cline.js

@@ -1,12 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { whichBinary } from '../utils/which.js';
 import { buildSkillMd } from './types.js';
-import { mergeJsonMcpServers } from './utils/json-config.js';
+import { mergeJsonMcpServers, removeRunworkMcpServers } from './utils/json-config.js';
 export class ClineAdapter {
     name = 'Cline';
     slug = 'cline';
+    mcpProvidesSkills = true;
     async detect() {
         return !!whichBinary('cline');
     }
@@ -85,4 +86,45 @@ export class ClineAdapter {
         mkdirSync(join(globalStatePath, '..'), { recursive: true });
         writeFileSync(globalStatePath, JSON.stringify(state, null, 2));
     }
+    // ── Cleanup (uninstall) ────────────────────────────────────────────
+    async cleanup(scope, manifest) {
+        // 1. Remove MCP entries (user scope only)
+        if (scope === 'user') {
+            const configPath = join(homedir(), '.cline', 'data', 'settings', 'cline_mcp_settings.json');
+            removeRunworkMcpServers(configPath, 'mcpServers');
+        }
+        // 2. Remove rule files (project scope only)
+        if (scope === 'project') {
+            const rulesDir = join(process.cwd(), '.clinerules');
+            if (existsSync(rulesDir)) {
+                for (const file of ['runwork.md', 'runwork-team.md']) {
+                    const filePath = join(rulesDir, file);
+                    if (existsSync(filePath)) {
+                        try {
+                            unlinkSync(filePath);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                }
+                // Remove only skill .md files that we synced
+                if (manifest?.skillFilenames.length) {
+                    const allowed = new Set(manifest.skillFilenames.map(f => `${f}.md`));
+                    for (const entry of readdirSync(rulesDir)) {
+                        if (allowed.has(entry)) {
+                            try {
+                                unlinkSync(join(rulesDir, entry));
+                            }
+                            catch { /* best-effort */ }
+                        }
+                    }
+                }
+                // Remove dir if empty
+                try {
+                    if (readdirSync(rulesDir).length === 0)
+                        rmSync(rulesDir, { recursive: true });
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
 }

package/dist/agents/codex.d.ts

@@ -1,7 +1,8 @@
-import type { AgentAdapter, AgentConfigOverride, AgentUsageStats, McpServerEntry, SkillFile } from './types.js';
+import type { AgentAdapter, AgentConfigOverride, AgentUsageStats, CleanupManifest, McpServerEntry, SkillFile } from './types.js';
 export declare class CodexAdapter implements AgentAdapter {
     name: string;
     slug: string;
+    mcpProvidesSkills: boolean;
     detect(): Promise<boolean>;
     supportsMcpScope(_scope: 'project' | 'user'): boolean;
     supportsSkills(): boolean;
@@ -10,6 +11,7 @@ export declare class CodexAdapter implements AgentAdapter {
     writeInstructionHint(hint: string, scope: 'project' | 'user'): Promise<void>;
     writeTeamInstructions(instructions: string, scope: 'project' | 'user'): Promise<void>;
     writeAgentConfig(config: AgentConfigOverride, scope: 'project' | 'user'): Promise<void>;
+    cleanup(scope: 'project' | 'user', manifest?: CleanupManifest): Promise<void>;
     readUsageStats(lastSyncAt: string | null): Promise<AgentUsageStats | null>;
     readVersion(): Promise<string | null>;
 }

package/dist/agents/codex.js

@@ -1,14 +1,20 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { parse, stringify } from 'smol-toml';
-import { buildSkillMd } from './types.js';
-import { writeHintToFile, writeTeamInstructionsToFile } from './utils/instruction-hint.js';
+import { buildSkillMd, appendTokenToUrl, RUNWORK_WORKSPACE_MCP_NAME } from './types.js';
+function isRunworkManagedCodexKey(key) {
+    return (key === RUNWORK_WORKSPACE_MCP_NAME ||
+        key.startsWith('runwork-') ||
+        key.startsWith('Runwork-'));
+}
+import { writeHintToFile, writeTeamInstructionsToFile, removeHintFromFile, removeTeamInstructionsFromFile } from './utils/instruction-hint.js';
 import { querySqlite } from '../utils/sqlite.js';
 import { whichBinary } from '../utils/which.js';
 export class CodexAdapter {
     name = 'Codex';
     slug = 'codex';
+    mcpProvidesSkills = true;
     async detect() {
         return !!whichBinary('codex');
     }
@@ -29,16 +35,22 @@ export class CodexAdapter {
             parsed.mcp_servers = {};
         }
         const mcpServers = parsed.mcp_servers;
-        // Remove existing runwork-* entries
+        // Remove existing runwork-managed entries. Handles legacy lowercase
+        // ("runwork-foo"), sanitized PascalCase ("Runwork-foo"), and the bare
+        // workspace-tools name ("Runwork").
         for (const key of Object.keys(mcpServers)) {
-            if (key.startsWith('runwork-'))
+            if (isRunworkManagedCodexKey(key)) {
                 delete mcpServers[key];
+            }
         }
-        // Add new entries
+        // Add new entries (sanitize names to match Codex's ^[a-zA-Z0-9_-]+$ requirement)
         for (const s of servers) {
-            mcpServers[s.name] = {
-                url: s.url,
-                ...(s.headers?.Authorization ? { bearer_token_env_var: 'RUNWORK_MCP_TOKEN' } : {}),
+            const safeName = s.name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+            // Embed auth token in URL so Codex doesn't need a separate env var
+            const token = s.headers?.Authorization?.replace(/^Bearer\s+/i, '');
+            const serverUrl = token ? appendTokenToUrl(s.url, token) : s.url;
+            mcpServers[safeName] = {
+                url: serverUrl,
             };
         }
         mkdirSync(join(configPath, '..'), { recursive: true });
@@ -49,7 +61,16 @@ export class CodexAdapter {
             ? join(process.cwd(), '.codex', 'skills')
             : join(homedir(), '.codex', 'skills');
         for (const skill of skills) {
-            const skillDir = join(baseDir, skill.name);
+            if (skill.name !== skill.filename) {
+                const oldDir = join(baseDir, skill.name);
+                if (existsSync(oldDir)) {
+                    try {
+                        rmSync(oldDir, { recursive: true, force: true });
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            const skillDir = join(baseDir, skill.filename);
             mkdirSync(skillDir, { recursive: true });
             writeFileSync(join(skillDir, 'SKILL.md'), buildSkillMd(skill));
         }
@@ -57,13 +78,13 @@ export class CodexAdapter {
     async writeInstructionHint(hint, scope) {
         const filePath = scope === 'project'
             ? join(process.cwd(), 'AGENTS.md')
-            : join(homedir(), '.codex', 'instructions.md');
+            : join(homedir(), '.codex', 'AGENTS.md');
         writeHintToFile(filePath, hint);
     }
     async writeTeamInstructions(instructions, scope) {
         const filePath = scope === 'project'
             ? join(process.cwd(), 'AGENTS.md')
-            : join(homedir(), '.codex', 'instructions.md');
+            : join(homedir(), '.codex', 'AGENTS.md');
         writeTeamInstructionsToFile(filePath, instructions);
     }
     // ── Agent config (TOML) ───────────────────────────────────────────
@@ -89,6 +110,51 @@ export class CodexAdapter {
         mkdirSync(join(configPath, '..'), { recursive: true });
         writeFileSync(configPath, stringify(parsed));
     }
+    // ── Cleanup (uninstall) ────────────────────────────────────────────
+    async cleanup(scope, manifest) {
+        // 1. Remove MCP server entries from config.toml
+        const configPath = join(homedir(), '.codex', 'config.toml');
+        if (existsSync(configPath)) {
+            try {
+                const parsed = parse(readFileSync(configPath, 'utf-8'));
+                if (parsed.mcp_servers && typeof parsed.mcp_servers === 'object') {
+                    const mcpServers = parsed.mcp_servers;
+                    for (const key of Object.keys(mcpServers)) {
+                        // Codex TOML sanitizes names via writeMcpServers, so the JSON-style
+                        // "Runwork: " prefix is never actually written here. Match the real
+                        // on-disk forms: "runwork-*" (legacy), "Runwork-*" (previous), and
+                        // the bare "Runwork" name used for workspace tools.
+                        if (isRunworkManagedCodexKey(key)) {
+                            delete mcpServers[key];
+                        }
+                    }
+                }
+                writeFileSync(configPath, stringify(parsed));
+            }
+            catch { /* best-effort */ }
+        }
+        // 2. Remove only skill directories that we synced (listed in manifest)
+        const skillsDir = scope === 'project'
+            ? join(process.cwd(), '.codex', 'skills')
+            : join(homedir(), '.codex', 'skills');
+        if (existsSync(skillsDir) && manifest?.skillFilenames.length) {
+            const allowed = new Set(manifest.skillFilenames);
+            for (const entry of readdirSync(skillsDir)) {
+                if (!allowed.has(entry))
+                    continue;
+                try {
+                    rmSync(join(skillsDir, entry), { recursive: true, force: true });
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        // 3. Remove instruction hints and team instructions
+        const instructionFile = scope === 'project'
+            ? join(process.cwd(), 'AGENTS.md')
+            : join(homedir(), '.codex', 'AGENTS.md');
+        removeHintFromFile(instructionFile);
+        removeTeamInstructionsFromFile(instructionFile);
+    }
     // ── Usage stats (passive, best-effort) ─────────────────────────────
     async readUsageStats(lastSyncAt) {
         try {
@@ -100,9 +166,14 @@ export class CodexAdapter {
             const dbPath = join(codexDir, 'state_5.sqlite');
             if (!existsSync(dbPath))
                 return null;
-            const countResult = querySqlite(dbPath, `SELECT count(*) FROM threads WHERE created_at > ${sinceSec}`);
+            // Filter on updated_at, not created_at: long-lived threads can accumulate
+            // activity post-sync without ever being "newly created". tokens_used is a
+            // lifetime per-thread total — summing active threads here overcounts when
+            // a thread was already partially used before lastSyncAt, but it's a far
+            // better signal than "0 because no new threads were spawned".
+            const countResult = querySqlite(dbPath, `SELECT count(*) FROM threads WHERE updated_at > ${sinceSec}`);
             const sessionCount = parseInt(countResult) || 0;
-            const tokensResult = querySqlite(dbPath, `SELECT coalesce(sum(tokens_used), 0) FROM threads WHERE created_at > ${sinceSec}`);
+            const tokensResult = querySqlite(dbPath, `SELECT coalesce(sum(tokens_used), 0) FROM threads WHERE updated_at > ${sinceSec}`);
             const tokensUsed = parseInt(tokensResult) || 0;
             const latestResult = querySqlite(dbPath, `SELECT max(updated_at) FROM threads`);
             const latestSec = parseInt(latestResult) || 0;