tokrepo 3.3.3 → 3.5.0

package/bin/tokrepo.js

@@ -5,6 +5,7 @@ const path = require('path');
 const crypto = require('crypto');
 const https = require('https');
 const http = require('http');
+const os = require('os');
 const readline = require('readline');
 
 // ANSI colors
@@ -20,21 +21,41 @@ const C = {
   white: '\x1b[37m',
 };
 
-const CONFIG_DIR = path.join(require('os').homedir(), '.tokrepo');
+const CONFIG_DIR = path.join(os.homedir(), '.tokrepo');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG = '.tokrepo.json';
 const DEFAULT_API = 'https://api.tokrepo.com';
-const CLI_VERSION = '3.3.3';
-const VERSION_CHECK_FILE = path.join(require('os').homedir(), '.tokrepo', '.version-check');
+const CLI_VERSION = '3.5.0';
+const VERSION_CHECK_FILE = path.join(os.homedir(), '.tokrepo', '.version-check');
+const CODEX_DIR = path.join(os.homedir(), '.codex');
+const CODEX_SKILLS_DIR = path.join(CODEX_DIR, 'skills');
+const CODEX_TOKREPO_DIR = path.join(CODEX_DIR, 'tokrepo');
+const CODEX_MANIFEST_FILE = path.join(CODEX_TOKREPO_DIR, 'install-manifest.json');
+const SUPPORTED_INSTALL_TARGETS = ['gemini', 'codex'];
 
 // ─── Helpers ───
 
+function wantsJson(argv = process.argv) {
+  return argv.includes('--json') || argv.some(arg => arg.startsWith('--json=') && arg !== '--json=false');
+}
+
 function log(msg) { console.log(msg); }
 function success(msg) { log(`${C.green}✓${C.reset} ${msg}`); }
-function error(msg) { log(`${C.red}✗${C.reset} ${msg}`); process.exit(1); }
+function error(msg) {
+  if (wantsJson()) {
+    console.error(JSON.stringify({ error: msg }, null, 2));
+  } else {
+    log(`${C.red}✗${C.reset} ${msg}`);
+  }
+  process.exit(1);
+}
 function warn(msg) { log(`${C.yellow}!${C.reset} ${msg}`); }
 function info(msg) { log(`${C.cyan}→${C.reset} ${msg}`); }
 
+function outputJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
 function readConfig() {
   // P0: TOKREPO_TOKEN env var takes priority (enables Agent automation)
   const envToken = process.env.TOKREPO_TOKEN;
@@ -215,6 +236,12 @@ function guessTag(fileType) {
   return map[fileType] || null;
 }
 
+function parseCsvList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.flatMap(parseCsvList);
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
 // ─── Glob matching ───
 
 function matchGlob(pattern, filename) {
@@ -272,32 +299,61 @@ function parseArgs(argv) {
     args.command = argv[i];
     i++;
   }
+
+  const valueFlags = new Set([
+    'title', 'desc', 'tag', 'target', 'targets', 'keyword', 'types',
+    'kind', 'install-mode', 'install_mode', 'entrypoint', 'asset-kind', 'asset_kind',
+    'version',
+    'page', 'page-size', 'page_size', 'sort-by', 'sort_by',
+    'time-window', 'time_window',
+  ]);
+
+  const assignFlag = (rawName, value = true) => {
+    const name = rawName.replace(/^--?/, '');
+    const normalized = name.replace(/-/g, '_');
+    if (normalized === 'tag') {
+      if (!args.flags.tags) args.flags.tags = [];
+      args.flags.tags.push(value);
+      return;
+    }
+    if (normalized === 'page_size') {
+      args.flags.pageSize = value;
+    } else if (normalized === 'sort_by') {
+      args.flags.sortBy = value;
+    } else if (normalized === 'time_window') {
+      args.flags.timeWindow = value;
+    } else if (normalized === 'dry_run') {
+      args.flags.dryRun = value;
+    } else if (normalized === 'approve_mcp') {
+      args.flags.approveMcp = value;
+    } else if (normalized === 'install_mode') {
+      args.flags.installMode = value;
+    } else if (normalized === 'asset_kind') {
+      args.flags.assetKind = value;
+    }
+    args.flags[normalized] = value;
+  };
+
   while (i < argv.length) {
     const arg = argv[i];
-    if (arg === '--public') {
-      args.flags.public = true;
-    } else if (arg === '--private') {
-      args.flags.private = true;
-    } else if (arg === '--title' && i + 1 < argv.length) {
-      args.flags.title = argv[++i];
-    } else if (arg.startsWith('--title=')) {
-      args.flags.title = arg.split('=').slice(1).join('=');
-    } else if (arg === '--desc' && i + 1 < argv.length) {
-      args.flags.desc = argv[++i];
-    } else if (arg.startsWith('--desc=')) {
-      args.flags.desc = arg.split('=').slice(1).join('=');
-    } else if (arg === '--tag' && i + 1 < argv.length) {
-      if (!args.flags.tags) args.flags.tags = [];
-      args.flags.tags.push(argv[++i]);
-    } else if (arg.startsWith('--tag=')) {
-      if (!args.flags.tags) args.flags.tags = [];
-      args.flags.tags.push(arg.split('=').slice(1).join('='));
-    } else if (arg === '--target' && i + 1 < argv.length) {
-      args.flags.target = argv[++i];
-    } else if (arg.startsWith('--target=')) {
-      args.flags.target = arg.split('=').slice(1).join('=');
+    if (arg === '-h' || arg === '--help') {
+      args.flags.help = true;
     } else if (arg === '-y' || arg === '--yes') {
       args.flags.yes = true;
+    } else if (arg.startsWith('--')) {
+      const eqIndex = arg.indexOf('=');
+      if (eqIndex !== -1) {
+        const name = arg.slice(2, eqIndex);
+        const value = arg.slice(eqIndex + 1);
+        assignFlag(name, value);
+      } else {
+        const name = arg.slice(2);
+        if (valueFlags.has(name) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+          assignFlag(name, argv[++i]);
+        } else {
+          assignFlag(name, true);
+        }
+      }
     } else if (!arg.startsWith('-')) {
       args.positional.push(arg);
     }
@@ -388,10 +444,10 @@ async function cmdLogin() {
 
   if (useToken) {
     // Manual token flow
-    info('Paste your API token (from https://tokrepo.com/en/my/settings)');
+    info('Paste your API key (from https://tokrepo.com/en/my/settings)');
     log('');
-    const token = await ask('API Token:');
-    if (!token) error('Token is required');
+    const token = await ask('API Key:');
+    if (!token) error('API key is required');
     return await saveAndVerifyToken(token);
   }
 
@@ -530,6 +586,10 @@ async function cmdPush() {
   description = args.flags.desc || description || '';
   visibility = args.flags.public ? 1 : (args.flags.private ? 0 : (projectConfig?.visibility ?? 0));
   tags = args.flags.tags || tags || [];
+  const kind = args.flags.kind || args.flags.assetKind || projectConfig?.kind || projectConfig?.asset_kind || '';
+  const targetTools = parseCsvList(args.flags.targets || args.flags.target || projectConfig?.target_tools || projectConfig?.targetTools);
+  const installMode = args.flags.installMode || projectConfig?.install_mode || projectConfig?.installMode || '';
+  const entrypoint = args.flags.entrypoint || projectConfig?.entrypoint || '';
 
   // Read files and detect types
   const pushFiles = [];
@@ -569,6 +629,15 @@ async function cmdPush() {
   if (detectedTags.size > 0) {
     log(`  ${C.bold}Tags:${C.reset}       ${Array.from(detectedTags).join(', ')}`);
   }
+  const metadataSummary = [
+    kind ? `kind=${kind}` : '',
+    targetTools.length ? `target_tools=${targetTools.join(',')}` : '',
+    installMode ? `install_mode=${installMode}` : '',
+    entrypoint ? `entrypoint=${entrypoint}` : '',
+  ].filter(Boolean);
+  if (metadataSummary.length > 0) {
+    log(`  ${C.bold}Agent meta:${C.reset} ${metadataSummary.join(' · ')}`);
+  }
   log('');
 
   for (const f of pushFiles) {
@@ -590,6 +659,10 @@ async function cmdPush() {
       tags: Array.from(detectedTags),
       token_cost: String(Math.round(totalChars / 4)),
       visibility: visibility,
+      kind,
+      target_tools: targetTools,
+      install_mode: installMode,
+      entrypoint,
     }, config.token, config.api);
 
     log('');
@@ -684,7 +757,10 @@ function normalizeQuery(q) {
 //   - Full URL: "https://tokrepo.com/en/workflows/ca000374-f5d8-..."
 //   - @username/asset-name: search by author + keyword
 //   - Plain name: search by keyword
-async function resolveAssetId(input, config, apiBase) {
+async function resolveAssetId(input, config, apiBase, opts = {}) {
+  const emitInfo = (msg) => { if (!opts.quiet) info(msg); };
+  const emitWarn = (msg) => { if (!opts.quiet) warn(msg); };
+
   // Already a UUID
   if (/^[a-f0-9-]{36}$/.test(input)) return input;
 
@@ -697,7 +773,7 @@ async function resolveAssetId(input, config, apiBase) {
   if (atMatch) {
     const [, username, assetName] = atMatch;
     const normalizedName = normalizeQuery(assetName);
-    info(`Searching for "${normalizedName}" by @${username}...`);
+    emitInfo(`Searching for "${normalizedName}" by @${username}...`);
     // Search by keyword, then filter by author nickname
     const encoded = encodeURIComponent(normalizedName);
     try {
@@ -710,7 +786,7 @@ async function resolveAssetId(input, config, apiBase) {
       if (match) return match.uuid;
       // Fallback: return first result
       if (items.length > 0) {
-        warn(`No exact match for @${username}, using best match: "${items[0].title}"`);
+        emitWarn(`No exact match for @${username}, using best match: "${items[0].title}"`);
         return items[0].uuid;
       }
     } catch { /* fall through */ }
@@ -719,7 +795,7 @@ async function resolveAssetId(input, config, apiBase) {
 
   // Plain name: search by keyword (normalize separators)
   const normalizedInput = normalizeQuery(input);
-  info(`Searching for "${normalizedInput}"...`);
+  emitInfo(`Searching for "${normalizedInput}"...`);
   const encoded = encodeURIComponent(normalizedInput);
   try {
     const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=1&page_size=5&sort_by=views`, null, config?.token, apiBase);
@@ -732,19 +808,43 @@ async function resolveAssetId(input, config, apiBase) {
 // ─── Search ───
 
 async function cmdSearch() {
-  const rawQuery = process.argv.slice(3).join(' ');
-  if (!rawQuery) error('Usage: tokrepo search <keyword>');
+  const args = parseArgs(process.argv);
+  const rawQuery = args.flags.keyword || args.positional.join(' ');
+  if (!rawQuery) {
+    showSearchHelp();
+    process.exit(1);
+  }
 
   const query = normalizeQuery(rawQuery);
   const displayQuery = query !== rawQuery ? `"${rawQuery}" → "${query}"` : `"${query}"`;
-  log(`\n${C.bold}tokrepo search${C.reset} ${displayQuery}\n`);
+  if (!args.flags.json) log(`\n${C.bold}tokrepo search${C.reset} ${displayQuery}\n`);
 
   const config = readConfig();
   const apiBase = config?.api || DEFAULT_API;
 
   try {
     const encoded = encodeURIComponent(query);
-    const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=1&page_size=20&sort_by=views`, null, config?.token, apiBase);
+    const pageSize = Number(args.flags.pageSize || (args.flags.all ? 200 : 20)) || 20;
+    const sortBy = args.flags.sortBy || 'views';
+    let page = Number(args.flags.page || 1) || 1;
+    let data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=${page}&page_size=${pageSize}&sort_by=${encodeURIComponent(sortBy)}`, null, config?.token, apiBase);
+
+    if (args.flags.all) {
+      const list = [...(data.list || [])];
+      while (list.length < (data.total || 0)) {
+        page++;
+        const next = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=${page}&page_size=${pageSize}&sort_by=${encodeURIComponent(sortBy)}`, null, config?.token, apiBase);
+        const items = next.list || [];
+        if (items.length === 0) break;
+        list.push(...items);
+      }
+      data = { ...data, list };
+    }
+
+    if (args.flags.json) {
+      outputJson({ query, total: data.total || 0, count: (data.list || []).length, list: data.list || [] });
+      return;
+    }
 
     if (!data.list || data.list.length === 0) {
       info('No assets found.');
@@ -782,6 +882,44 @@ async function cmdSearch() {
   }
 }
 
+async function cmdDetail() {
+  const args = parseArgs(process.argv);
+  const target = args.positional[0];
+  if (!target) {
+    showDetailHelp();
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+
+  try {
+    const uuid = await resolveAssetId(target, config, apiBase, { quiet: Boolean(args.flags.json) });
+    const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${encodeURIComponent(uuid)}`, null, config?.token, apiBase);
+    if (args.flags.json) {
+      outputJson(data);
+      return;
+    }
+
+    const workflow = data.workflow;
+    log(`\n${C.bold}tokrepo detail${C.reset}\n`);
+    log(`  ${C.bold}${workflow.title}${C.reset}`);
+    if (workflow.description) log(`  ${C.dim}${workflow.description}${C.reset}`);
+    log(`\n  ${C.bold}UUID:${C.reset}  ${workflow.uuid}`);
+    log(`  ${C.bold}URL:${C.reset}   ${C.cyan}https://tokrepo.com/en/workflows/${workflow.uuid}${C.reset}`);
+    if (workflow.tags && workflow.tags.length) {
+      log(`  ${C.bold}Tags:${C.reset}  ${workflow.tags.map(t => t.name || t.slug).join(', ')}`);
+    }
+    const fileCount = (workflow.files || []).length;
+    const stepCount = (workflow.steps || []).length;
+    log(`  ${C.bold}Files:${C.reset} ${fileCount}`);
+    log(`  ${C.bold}Steps:${C.reset} ${stepCount}`);
+    log('');
+  } catch (e) {
+    error(`Detail failed: ${e.message}`);
+  }
+}
+
 // ─── Install (smart pull with correct placement) ───
 
 function normalizeInstallTarget(target) {
@@ -790,6 +928,9 @@ function normalizeInstallTarget(target) {
   const aliases = {
     gemini: 'gemini',
     'gemini-cli': 'gemini',
+    codex: 'codex',
+    'codex-cli': 'codex',
+    'openai-codex': 'codex',
   };
   return aliases[normalized] || normalized;
 }
@@ -797,8 +938,8 @@ function normalizeInstallTarget(target) {
 function validateInstallTarget(target) {
   if (!target) return '';
   const normalized = normalizeInstallTarget(target);
-  if (normalized !== 'gemini') {
-    error(`Unsupported install target: ${target}. Supported targets: gemini`);
+  if (!SUPPORTED_INSTALL_TARGETS.includes(normalized)) {
+    error(`Unsupported install target: ${target}. Supported targets: ${SUPPORTED_INSTALL_TARGETS.join(', ')}`);
   }
   return normalized;
 }
@@ -838,27 +979,497 @@ function formatGeminiContent(workflow, contents) {
   return `${parts.join('\n\n').trim()}\n`;
 }
 
+function getWorkflowAssetType(workflow) {
+  if (!workflow || !workflow.tags || workflow.tags.length === 0) return 'other';
+  return (workflow.tags[0].slug || workflow.tags[0].name || '').toLowerCase();
+}
+
+function extractInstallableContents(workflow, assetType) {
+  const contents = [];
+  const files = workflow.files || [];
+
+  if (files.length > 0) {
+    for (const f of files) {
+      if (f.content && !f.content.startsWith('PK')) {
+        contents.push({
+          name: f.name || 'SKILL.md',
+          content: f.content,
+          type: f.type || f.file_type || f.fileType || detectFileType(f.name || ''),
+        });
+      }
+    }
+  }
+
+  if (contents.length === 0 && workflow.steps) {
+    for (const step of workflow.steps) {
+      const content = step.prompt_template || step.promptTemplate;
+      if (content && !content.startsWith('PK')) {
+        const name = (step.title || `step-${step.step_order || contents.length + 1}`).replace(/[/\\?%*:|"<>]/g, '-');
+        contents.push({ name, content, type: assetType || 'other' });
+      }
+    }
+  }
+
+  return contents;
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(String(content || '')).digest('hex');
+}
+
+function slugify(input, fallback = 'asset') {
+  const raw = String(input || '')
+    .normalize('NFKD')
+    .replace(/[^\x00-\x7F]/g, '')
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+  return raw || fallback;
+}
+
+function sanitizePathSegment(input, fallback = 'file') {
+  const cleaned = String(input || '')
+    .replace(/[/\\?%*:|"<>]/g, '-')
+    .replace(/^\.+$/, '')
+    .replace(/^\.+/, '')
+    .trim();
+  return cleaned || fallback;
+}
+
+function sanitizeRelativePath(input, fallback = 'file.md') {
+  const normalized = String(input || fallback).replace(/\\/g, '/');
+  const parts = normalized
+    .split('/')
+    .filter(Boolean)
+    .map((part, index) => sanitizePathSegment(part, index === 0 ? fallback : 'file'));
+  let rel = parts.join('/');
+  if (!rel) rel = fallback;
+  if (!path.extname(rel)) rel += '.md';
+  return rel;
+}
+
+function ensureInside(baseDir, destPath) {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedDest = path.resolve(destPath);
+  return resolvedDest === resolvedBase || resolvedDest.startsWith(resolvedBase + path.sep);
+}
+
+function getFrontmatter(content) {
+  const text = String(content || '').replace(/^\uFEFF/, '');
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!match) return null;
+  return { raw: match[0], body: match[1], rest: text.slice(match[0].length) };
+}
+
+function getFrontmatterValue(content, key) {
+  const fm = getFrontmatter(content);
+  if (!fm) return '';
+  const re = new RegExp(`^${key}\\s*:\\s*(.+)$`, 'im');
+  const match = fm.body.match(re);
+  if (!match) return '';
+  return match[1].trim().replace(/^['"]|['"]$/g, '');
+}
+
+function isCodexSkillDocument(item) {
+  const content = item?.content || '';
+  const name = getFrontmatterValue(content, 'name');
+  const description = getFrontmatterValue(content, 'description');
+  return Boolean(name && description) || /^skill\.md$/i.test(path.basename(item?.name || ''));
+}
+
+function yamlQuoted(value) {
+  return JSON.stringify(String(value || '').replace(/\s+/g, ' ').trim());
+}
+
+function ensureCodexSkillFrontmatter(content, name, description) {
+  const text = String(content || '').replace(/^\uFEFF/, '').trim();
+  const fm = getFrontmatter(text);
+  if (!fm) {
+    return `---\nname: ${name}\ndescription: ${yamlQuoted(description)}\n---\n\n${text}\n`;
+  }
+
+  const lines = fm.body.split('\n');
+  const hasName = lines.some(line => /^name\s*:/i.test(line));
+  const hasDescription = lines.some(line => /^description\s*:/i.test(line));
+  const next = [];
+  if (!hasName) next.push(`name: ${name}`);
+  if (!hasDescription) next.push(`description: ${yamlQuoted(description)}`);
+  next.push(...lines);
+  return `---\n${next.join('\n')}\n---\n${fm.rest.trim() ? `\n${fm.rest.trim()}\n` : '\n'}`;
+}
+
+function getCodexDescription(workflow, item) {
+  const fromItem = getFrontmatterValue(item?.content || '', 'description');
+  if (fromItem) return fromItem;
+  const title = workflow?.title || item?.name || 'TokRepo asset';
+  const desc = workflow?.description || '';
+  return desc ? desc.substring(0, 240) : `Use ${title} from TokRepo.`;
+}
+
+function codexSkillDirName(workflow, item, suffix = '') {
+  const uuid8 = (workflow?.uuid || '').substring(0, 8) || 'asset';
+  const fmName = getFrontmatterValue(item?.content || '', 'name');
+  const base = fmName || item?.name || workflow?.slug || workflow?.title || uuid8;
+  const baseSlug = slugify(base, uuid8).replace(/-md$/, '');
+  const withSuffix = suffix ? `${baseSlug}-${slugify(suffix, 'part')}` : baseSlug;
+  if (withSuffix.startsWith('tokrepo-') && withSuffix.endsWith(`-${uuid8}`)) return withSuffix;
+  if (withSuffix.startsWith('tokrepo-')) return `${withSuffix}-${uuid8}`;
+  if (withSuffix.endsWith(`-${uuid8}`)) return `tokrepo-${withSuffix}`;
+  return `tokrepo-${withSuffix}-${uuid8}`;
+}
+
+function explicitInstallMode(workflow) {
+  const candidates = [
+    workflow?.installMode,
+    workflow?.install_mode,
+    workflow?.agent_metadata?.install_mode,
+    workflow?.agentMetadata?.installMode,
+    workflow?.metadata?.installMode,
+    workflow?.metadata?.install_mode,
+  ].filter(Boolean);
+  const mode = String(candidates[0] || '').toLowerCase();
+  return ['single', 'bundle', 'split', 'stage_only'].includes(mode) ? mode : '';
+}
+
+function inferCodexInstallMode(workflow, contents) {
+  const explicit = explicitInstallMode(workflow);
+  if (explicit) return explicit;
+  if (contents.length <= 1) return 'single';
+  const skillDocs = contents.filter(isCodexSkillDocument);
+  if (skillDocs.length > 1 && skillDocs.length === contents.length) return 'split';
+  return 'bundle';
+}
+
+function analyzeInstallRisks(fileName, content, type) {
+  const risks = new Set();
+  const lowerName = String(fileName || '').toLowerCase();
+  const text = String(content || '');
+  if (type === 'script' || /\.(sh|py|js|mjs|ts|rb|go|rs|lua)$/.test(lowerName) || /^#!\//.test(text)) {
+    risks.add('executable');
+  }
+  if (lowerName.endsWith('.mcp.json') || /"mcpServers"\s*:/.test(text) || /\bmcpServers\s*:/.test(text)) {
+    risks.add('mcp');
+  }
+  if (/\b(PATH|HOME|TOKEN|API_KEY|SECRET|PASSWORD|OPENAI_API_KEY|ANTHROPIC_API_KEY)\b/.test(text)) {
+    risks.add('env');
+  }
+  if (/(^|[\s"'=])\/(Users|opt|usr|var|etc|tmp)\//.test(text) || /[A-Za-z]:\\/.test(text)) {
+    risks.add('absolute-path');
+  }
+  return Array.from(risks);
+}
+
+function buildBundleEntrypoint(workflow, contents, skillName) {
+  const title = workflow.title || 'TokRepo Asset';
+  const sourceUrl = `https://tokrepo.com/en/workflows/${workflow.uuid}`;
+  const fileList = contents
+    .map((item, index) => `- ${sanitizeRelativePath(item.name || `file-${index + 1}.md`)}`)
+    .join('\n');
+  const body = `# ${title}\n\nThis Codex skill was installed from TokRepo as a bundle. Use the files in this directory as the source material for the skill.\n\n${fileList}\n\nSource: ${sourceUrl}\n`;
+  return ensureCodexSkillFrontmatter(body, skillName, getCodexDescription(workflow));
+}
+
+function addPlanFile(plan, destPath, content, sourceName, type) {
+  const riskFlags = analyzeInstallRisks(sourceName || destPath, content, type);
+  plan.files.push({
+    path: destPath,
+    sourceName: sourceName || path.basename(destPath),
+    sha256: sha256(content),
+    bytes: Buffer.byteLength(String(content || '')),
+    riskFlags,
+    content,
+  });
+  for (const risk of riskFlags) {
+    if (!plan.risks.includes(risk)) plan.risks.push(risk);
+  }
+}
+
+function buildCodexInstallPlan(workflow, contents, opts = {}) {
+  const installMode = opts.installMode || inferCodexInstallMode(workflow, contents);
+  const agentMetadata = workflow?.agent_metadata || workflow?.agentMetadata || {};
+  const plan = {
+    uuid: workflow.uuid,
+    title: workflow.title,
+    sourceUrl: `https://tokrepo.com/en/workflows/${workflow.uuid}`,
+    targetTool: 'codex',
+    installMode,
+    manifestPath: CODEX_MANIFEST_FILE,
+    files: [],
+    risks: [],
+    agentMetadata,
+    contentHash: workflow.content_hash || workflow.contentHash || agentMetadata.content_hash || '',
+  };
+
+  if (installMode === 'stage_only') {
+    const stageDir = path.join(CODEX_TOKREPO_DIR, 'staged', workflow.uuid);
+    plan.baseDir = stageDir;
+    contents.forEach((item, index) => {
+      const relName = sanitizeRelativePath(item.name || `file-${index + 1}.md`);
+      addPlanFile(plan, path.join(stageDir, relName), `${String(item.content || '').trim()}\n`, item.name, item.type);
+    });
+    return plan;
+  }
+
+  if (installMode === 'split') {
+    const usedDirs = new Set();
+    contents.forEach((item, index) => {
+      const skillName = slugify(getFrontmatterValue(item.content, 'name') || item.name || `${workflow.title}-${index + 1}`, `${workflow.uuid.substring(0, 8)}-${index + 1}`);
+      const baseDirName = codexSkillDirName(workflow, item, contents.length > 1 && !getFrontmatterValue(item.content, 'name') ? String(index + 1) : '');
+      let dirName = baseDirName;
+      let duplicateIndex = 2;
+      while (usedDirs.has(dirName)) {
+        dirName = `${baseDirName}-${duplicateIndex}`;
+        duplicateIndex++;
+      }
+      usedDirs.add(dirName);
+      const destDir = path.join(CODEX_SKILLS_DIR, dirName);
+      const destPath = path.join(destDir, 'SKILL.md');
+      const content = ensureCodexSkillFrontmatter(item.content, skillName, getCodexDescription(workflow, item));
+      addPlanFile(plan, destPath, content, item.name, item.type);
+    });
+    return plan;
+  }
+
+  const primaryItem = contents.find(item => /^skill\.md$/i.test(path.basename(item.name || ''))) || contents[0];
+  const skillName = slugify(getFrontmatterValue(primaryItem?.content || '', 'name') || workflow.slug || workflow.title, workflow.uuid.substring(0, 8));
+  const dirItem = getFrontmatterValue(primaryItem?.content || '', 'name') ? primaryItem : null;
+  const destDir = path.join(CODEX_SKILLS_DIR, codexSkillDirName(workflow, dirItem));
+  plan.baseDir = destDir;
+
+  if (installMode === 'single' || contents.length === 1) {
+    const item = primaryItem;
+    const content = ensureCodexSkillFrontmatter(item.content, skillName, getCodexDescription(workflow, item));
+    addPlanFile(plan, path.join(destDir, 'SKILL.md'), content, item.name, item.type);
+    return plan;
+  }
+
+  let hasEntrypoint = false;
+  const usedRelNames = new Set();
+  for (let i = 0; i < contents.length; i++) {
+    const item = contents[i];
+    const relName = sanitizeRelativePath(item.name || `file-${i + 1}.md`);
+    let destName = /^skill\.md$/i.test(path.basename(relName)) ? 'SKILL.md' : relName;
+    if (usedRelNames.has(destName)) {
+      const ext = path.extname(destName);
+      const base = destName.slice(0, destName.length - ext.length);
+      let duplicateIndex = 2;
+      let candidate = `${base}-${duplicateIndex}${ext}`;
+      while (usedRelNames.has(candidate)) {
+        duplicateIndex++;
+        candidate = `${base}-${duplicateIndex}${ext}`;
+      }
+      destName = candidate;
+    }
+    usedRelNames.add(destName);
+    const destPath = path.join(destDir, destName);
+    const content = destName === 'SKILL.md'
+      ? ensureCodexSkillFrontmatter(item.content, skillName, getCodexDescription(workflow, item))
+      : `${String(item.content || '').trim()}\n`;
+    if (destName === 'SKILL.md') hasEntrypoint = true;
+    addPlanFile(plan, destPath, content, item.name, item.type);
+  }
+
+  if (!hasEntrypoint) {
+    addPlanFile(plan, path.join(destDir, 'SKILL.md'), buildBundleEntrypoint(workflow, contents, skillName), 'SKILL.md', 'skill');
+  }
+
+  return plan;
+}
+
+function publicInstallPlan(plan) {
+  return {
+    uuid: plan.uuid,
+    title: plan.title,
+    sourceUrl: plan.sourceUrl,
+    targetTool: plan.targetTool,
+    installMode: plan.installMode,
+    manifestPath: plan.manifestPath,
+    baseDir: plan.baseDir,
+    risks: plan.risks,
+    requiresConfirmation: hasCodexInstallRisks(plan),
+    contentHash: plan.contentHash || '',
+    agentMetadata: plan.agentMetadata || {},
+    files: plan.files.map(file => ({
+      path: file.path,
+      sourceName: file.sourceName,
+      sha256: file.sha256,
+      bytes: file.bytes,
+      riskFlags: file.riskFlags,
+      exists: fs.existsSync(file.path),
+    })),
+  };
+}
+
+function hasCodexInstallRisks(plan) {
+  return (plan.risks || []).some(risk => ['mcp', 'executable', 'env', 'absolute-path'].includes(risk));
+}
+
+function formatRiskLine(file) {
+  if (!file.riskFlags || file.riskFlags.length === 0) return '';
+  return `${file.sourceName || path.basename(file.path)}: ${file.riskFlags.join(', ')}`;
+}
+
+async function confirmCodexInstallRisks(plan, opts = {}) {
+  if (plan.installMode === 'stage_only') return;
+  if (opts.dryRun || opts.stage || !hasCodexInstallRisks(plan)) return;
+  if (opts.approveMcp || opts.approve_mcp || opts.yes) return;
+
+  if (opts.json || opts.throwOnError || process.env.TOKREPO_NONINTERACTIVE === '1') {
+    throw new Error(`Install plan includes risky content (${plan.risks.join(', ')}). Re-run with --dry-run to inspect or --approve-mcp to approve writing the Codex skill bundle.`);
+  }
+
+  warn(`This asset contains ${plan.risks.join(', ')} content.`);
+  log(`  ${C.dim}TokRepo will only write files under ${CODEX_SKILLS_DIR}; it will not merge MCP configs, modify PATH, or execute scripts.${C.reset}`);
+  const riskyFiles = plan.files
+    .map(formatRiskLine)
+    .filter(Boolean)
+    .slice(0, 8);
+  for (const line of riskyFiles) {
+    log(`  ${C.yellow}!${C.reset} ${line}`);
+  }
+  if (plan.files.length > riskyFiles.length) {
+    log(`  ${C.dim}...and ${plan.files.length - riskyFiles.length} more file(s) in the plan${C.reset}`);
+  }
+
+  const answer = await ask('Write this Codex skill bundle anyway? (y/N):');
+  if (answer.toLowerCase() !== 'y') {
+    throw new Error('Install aborted.');
+  }
+}
+
+function stageCodexInstallPlan(plan) {
+  const stagedDir = path.join(CODEX_TOKREPO_DIR, 'staged');
+  if (!fs.existsSync(stagedDir)) {
+    fs.mkdirSync(stagedDir, { recursive: true, mode: 0o700 });
+  }
+  const stagePath = path.join(stagedDir, `${plan.uuid}.install-plan.json`);
+  fs.writeFileSync(stagePath, `${JSON.stringify(publicInstallPlan(plan), null, 2)}\n`, { mode: 0o600 });
+  return stagePath;
+}
+
+function executeStageOnlyCodexPlan(plan) {
+  const installedFiles = [];
+  const stageRoot = path.join(CODEX_TOKREPO_DIR, 'staged', plan.uuid);
+  if (!fs.existsSync(stageRoot)) fs.mkdirSync(stageRoot, { recursive: true, mode: 0o700 });
+
+  for (const file of plan.files) {
+    if (!ensureInside(stageRoot, file.path)) {
+      throw new Error(`Stage path escaped TokRepo staging directory: ${file.path}`);
+    }
+    const destDir = path.dirname(file.path);
+    if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file.path, file.content, { mode: 0o600 });
+    installedFiles.push({
+      path: file.path,
+      sourceName: file.sourceName,
+      sha256: sha256(file.content),
+      bytes: Buffer.byteLength(String(file.content || '')),
+      riskFlags: file.riskFlags,
+    });
+  }
+
+  const stagePath = path.join(stageRoot, 'install-plan.json');
+  fs.writeFileSync(stagePath, `${JSON.stringify(publicInstallPlan(plan), null, 2)}\n`, { mode: 0o600 });
+  return { dryRun: true, staged: true, stageOnly: true, stagePath, plan: publicInstallPlan(plan), installedFiles };
+}
+
+function readCodexManifest() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CODEX_MANIFEST_FILE, 'utf8'));
+    if (Array.isArray(parsed.installs)) return parsed;
+  } catch {}
+  return { schemaVersion: 1, installs: [] };
+}
+
+function writeCodexManifestRecord(plan, installedFiles) {
+  if (!fs.existsSync(CODEX_TOKREPO_DIR)) {
+    fs.mkdirSync(CODEX_TOKREPO_DIR, { recursive: true, mode: 0o700 });
+  }
+  const manifest = readCodexManifest();
+  const installedAt = new Date().toISOString();
+  const record = {
+    uuid: plan.uuid,
+    title: plan.title,
+    sourceUrl: plan.sourceUrl,
+    targetTool: 'codex',
+    installMode: plan.installMode,
+    installedAt,
+    contentHash: plan.contentHash || '',
+    agentMetadata: plan.agentMetadata || {},
+    installedFiles: installedFiles.map(file => ({
+      path: file.path,
+      sourceName: file.sourceName,
+      sha256: file.sha256,
+      bytes: file.bytes,
+      riskFlags: file.riskFlags,
+    })),
+    risks: plan.risks,
+  };
+  manifest.installs = manifest.installs.filter(item => !(item.uuid === plan.uuid && item.targetTool === 'codex'));
+  manifest.installs.push(record);
+  manifest.updatedAt = installedAt;
+  fs.writeFileSync(CODEX_MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  return record;
+}
+
+function executeCodexInstallPlan(plan, opts = {}) {
+  if (opts.dryRun) return { dryRun: true, plan: publicInstallPlan(plan), installedFiles: [] };
+  if (plan.installMode === 'stage_only') return executeStageOnlyCodexPlan(plan);
+  if (opts.stage) {
+    const stagePath = stageCodexInstallPlan(plan);
+    return { dryRun: true, staged: true, stagePath, plan: publicInstallPlan(plan), installedFiles: [] };
+  }
+
+  const installedFiles = [];
+  for (const file of plan.files) {
+    const destDir = path.dirname(file.path);
+    if (!ensureInside(CODEX_SKILLS_DIR, file.path)) {
+      throw new Error(`Install path escaped Codex skills directory: ${file.path}`);
+    }
+    if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(file.path, file.content);
+    installedFiles.push({
+      path: file.path,
+      sourceName: file.sourceName,
+      sha256: sha256(file.content),
+      bytes: Buffer.byteLength(String(file.content || '')),
+      riskFlags: file.riskFlags,
+    });
+  }
+
+  const manifestRecord = writeCodexManifestRecord(plan, installedFiles);
+  return { dryRun: false, plan: publicInstallPlan(plan), installedFiles, manifestRecord };
+}
+
+async function installCodexAsset(workflow, contents, opts = {}) {
+  const plan = buildCodexInstallPlan(workflow, contents, opts);
+  await confirmCodexInstallRisks(plan, opts);
+  return executeCodexInstallPlan(plan, opts);
+}
+
 async function cmdInstall() {
   const args = parseArgs(process.argv);
   const target = args.positional[0];
   if (!target) {
-    error(`Usage: tokrepo install <target> [--target gemini] [--yes]
-
-Examples:
-  tokrepo install awesome-cursor-rules                # by name
-  tokrepo install ca000374-f5d8-4d75-a30c-460fda0b6b0e  # by uuid
-  tokrepo install https://tokrepo.com/en/workflows/ca000374-...
-  tokrepo install pack/seo-geo                        # install whole theme pack
-  tokrepo install c4b18aeb --target gemini            # write .gemini/GEMINI.md`);
+    showInstallHelp();
+    process.exit(1);
   }
 
-  log(`\n${C.bold}tokrepo install${C.reset}\n`);
+  if (!args.flags.json) log(`\n${C.bold}tokrepo install${C.reset}\n`);
 
   const config = readConfig();
   const apiBase = config?.api || DEFAULT_API;
   const installOpts = {
     targetTool: validateInstallTarget(args.flags.target),
     yes: Boolean(args.flags.yes),
+    update: Boolean(args.flags.update),
+    dryRun: Boolean(args.flags.dryRun || args.flags.dry_run),
+    stage: Boolean(args.flags.stage),
+    approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+    json: Boolean(args.flags.json),
+    manifest: Boolean(args.flags.manifest),
   };
 
   // pack/<slug> dispatch — install entire theme pack
@@ -871,7 +1482,10 @@ Examples:
     return;
   }
 
-  await installOneAsset(target, config, apiBase, installOpts);
+  const result = await installOneAsset(target, config, apiBase, installOpts);
+  if (args.flags.json) {
+    outputJson(result);
+  }
 }
 
 // Install all assets in a theme pack — sequentially, continue past per-item errors
@@ -916,6 +1530,7 @@ async function installPack(slug, config, apiBase, opts) {
 async function installOneAsset(target, config, apiBase, opts) {
   opts = opts || {};
   const die = (msg) => { if (opts.throwOnError) throw new Error(msg); error(msg); };
+  const emitInfo = (msg) => { if (!opts.json) info(msg); };
 
   // Resolve target to UUID
   let uuid = target;
@@ -946,7 +1561,7 @@ async function installOneAsset(target, config, apiBase, opts) {
   if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(uuid)) {
     // Search by name (normalize separators for better matching)
     const normalizedTarget = normalizeQuery(uuid);
-    info(`Searching for "${normalizedTarget}"...`);
+    emitInfo(`Searching for "${normalizedTarget}"...`);
     try {
       const encoded = encodeURIComponent(normalizedTarget);
       const searchData = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encoded}&page=1&page_size=5&sort_by=views`, null, config?.token, apiBase);
@@ -964,61 +1579,91 @@ async function installOneAsset(target, config, apiBase, opts) {
       const chosen = exact || searchData.list[0];
 
       uuid = chosen.uuid;
-      info(`Found: ${C.bold}${chosen.title}${C.reset}`);
+      emitInfo(`Found: ${C.bold}${chosen.title}${C.reset}`);
     } catch (e) {
       die(`Search failed: ${e.message}`);
     }
   }
 
   // Fetch the asset
-  info(`Fetching ${uuid.substring(0, 8)}...`);
+  emitInfo(`Fetching ${uuid.substring(0, 8)}...`);
 
-  let workflow, files;
+  let workflow;
   try {
     const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${uuid}`, null, config?.token, apiBase);
     workflow = data.workflow;
-    files = data.workflow.files || [];
   } catch (e) {
     die(`Fetch failed: ${e.message}`);
   }
 
-  log(`\n  ${C.bold}${workflow.title}${C.reset}`);
-  if (workflow.description) log(`  ${C.dim}${workflow.description.substring(0, 100)}${C.reset}`);
+  if (!opts.json) {
+    log(`\n  ${C.bold}${workflow.title}${C.reset}`);
+    if (workflow.description) log(`  ${C.dim}${workflow.description.substring(0, 100)}${C.reset}`);
+  }
 
   // Determine asset type from tags
-  let assetType = 'other';
-  if (workflow.tags && workflow.tags.length > 0) {
-    assetType = (workflow.tags[0].slug || workflow.tags[0].name || '').toLowerCase();
-  }
+  let assetType = getWorkflowAssetType(workflow);
 
   // Get content — prefer files, fallback to steps
-  const contents = [];
+  const contents = extractInstallableContents(workflow, assetType);
 
-  if (files.length > 0) {
-    for (const f of files) {
-      if (f.content && !f.content.startsWith('PK')) {
-        contents.push({ name: f.name, content: f.content, type: f.file_type || f.fileType || 'other' });
-      }
-    }
+  if (contents.length === 0) {
+    die('No installable content found in this asset.');
   }
 
-  if (contents.length === 0 && workflow.steps) {
-    for (const step of workflow.steps) {
-      const content = step.prompt_template || step.promptTemplate;
-      if (content && !content.startsWith('PK')) {
-        const name = (step.title || `step-${step.step_order}`).replace(/[/\\?%*:|"<>]/g, '-');
-        contents.push({ name, content, type: assetType });
+  if (!opts.json) log('');
+  const targetTool = normalizeInstallTarget(opts.targetTool);
+
+  if (targetTool === 'codex') {
+    let result;
+    try {
+      result = await installCodexAsset(workflow, contents, opts);
+    } catch (e) {
+      die(e.message);
+    }
+
+    if (!opts.json) {
+      const plan = result.plan;
+      if (result.staged || opts.stage) {
+        info(`Staged install plan: ${result.stagePath}`);
+        if (result.stageOnly) {
+          info(`stage_only asset: files were written only under ${path.dirname(result.stagePath)}; no Codex skill was activated.`);
+        } else {
+          info(`No Codex skill files were written. Re-run with --approve-mcp or --yes to install.`);
+        }
+      } else if (opts.dryRun) {
+        info(`Dry run: ${plan.files.length} file(s) would be installed to ${CODEX_SKILLS_DIR}`);
+        for (const file of plan.files) {
+          const rel = path.relative(os.homedir(), file.path);
+          log(`  ${C.dim}•${C.reset} ~/${rel}`);
+          if (file.riskFlags.length) log(`    ${C.yellow}${file.riskFlags.join(', ')}${C.reset}`);
+        }
+      } else {
+        for (const file of result.installedFiles) {
+          const relPath = path.relative(os.homedir(), file.path);
+          success(`Installed: ~/${relPath}`);
+        }
+        log('');
+        success(`${result.installedFiles.length} file(s) installed from ${C.bold}${workflow.title}${C.reset}`);
+        log(`  ${C.dim}Manifest: ${CODEX_MANIFEST_FILE}${C.reset}`);
+        log(`  ${C.dim}Source: https://tokrepo.com/en/workflows/${uuid}${C.reset}\n`);
       }
     }
-  }
 
-  if (contents.length === 0) {
-    die('No installable content found in this asset.');
+    return {
+      uuid,
+      title: workflow.title,
+      targetTool: 'codex',
+      dryRun: Boolean(opts.dryRun || opts.stage),
+      staged: Boolean(result.staged),
+      stagePath: result.stagePath,
+      installMode: result.plan.installMode,
+      installedFiles: result.installedFiles || [],
+      plan: result.plan,
+      manifestPath: CODEX_MANIFEST_FILE,
+    };
   }
 
-  log('');
-  const targetTool = normalizeInstallTarget(opts.targetTool);
-
   if (targetTool === 'gemini') {
     const destDir = path.join(process.cwd(), '.gemini');
     if (!fs.existsSync(destDir)) {
@@ -1039,7 +1684,13 @@ async function installOneAsset(target, config, apiBase, opts) {
     log('');
     success(`1 file installed from ${C.bold}${workflow.title}${C.reset}`);
     log(`  ${C.dim}Source: https://tokrepo.com/en/workflows/${uuid}${C.reset}\n`);
-    return;
+    return {
+      uuid,
+      title: workflow.title,
+      targetTool: 'gemini',
+      installedFiles: [{ path: destPath }],
+      sourceUrl: `https://tokrepo.com/en/workflows/${uuid}`,
+    };
   }
 
   // Smart install based on asset type
@@ -1122,6 +1773,13 @@ async function installOneAsset(target, config, apiBase, opts) {
   log('');
   success(`${installed} file(s) installed from ${C.bold}${workflow.title}${C.reset}`);
   log(`  ${C.dim}Source: https://tokrepo.com/en/workflows/${uuid}${C.reset}\n`);
+  return {
+    uuid,
+    title: workflow.title,
+    targetTool: targetTool || 'project',
+    installed,
+    sourceUrl: `https://tokrepo.com/en/workflows/${uuid}`,
+  };
 }
 
 async function cmdWhoami() {
@@ -1141,13 +1799,33 @@ async function cmdWhoami() {
 }
 
 async function cmdList() {
-  log(`\n${C.bold}tokrepo list${C.reset}\n`);
+  const args = parseArgs(process.argv);
+  if (!args.flags.json) log(`\n${C.bold}tokrepo list${C.reset}\n`);
 
   const config = readConfig();
   if (!config || !config.token) error('Not logged in. Run: tokrepo login');
 
   try {
-    const data = await apiRequest('GET', '/api/v1/tokenboard/workflows/my?page=1&page_size=50', null, config.token, config.api);
+    const pageSize = Number(args.flags.pageSize || (args.flags.all ? 200 : 50)) || 50;
+    let page = Number(args.flags.page || 1) || 1;
+    let data = await apiRequest('GET', `/api/v1/tokenboard/workflows/my?page=${page}&page_size=${pageSize}`, null, config.token, config.api);
+
+    if (args.flags.all) {
+      const list = [...(data.list || [])];
+      while (list.length < (data.total || 0)) {
+        page++;
+        const next = await apiRequest('GET', `/api/v1/tokenboard/workflows/my?page=${page}&page_size=${pageSize}`, null, config.token, config.api);
+        const items = next.list || [];
+        if (items.length === 0) break;
+        list.push(...items);
+      }
+      data = { ...data, list };
+    }
+
+    if (args.flags.json) {
+      outputJson({ total: data.total || 0, count: (data.list || []).length, list: data.list || [] });
+      return;
+    }
 
     if (!data.list || data.list.length === 0) {
       info('No assets found. Run: tokrepo push');
@@ -1167,6 +1845,12 @@ async function cmdList() {
 }
 
 async function cmdUpdate() {
+  const args = parseArgs(process.argv);
+  if (args.flags.target || args.flags.all || args.flags.force) {
+    await cmdSyncInstalled();
+    return;
+  }
+
   const uuid = process.argv[3];
   if (!uuid) error('Usage: tokrepo update <uuid> [file]');
 
@@ -1232,107 +1916,515 @@ async function cmdDelete() {
   }
 }
 
+function tagMatchesTypes(workflow, requestedTypes) {
+  if (!requestedTypes || requestedTypes.length === 0) return true;
+  const tags = (workflow.tags || []).flatMap(t => [t.slug, t.name]).filter(Boolean).map(t => String(t).toLowerCase());
+  const assetType = getWorkflowAssetType(workflow);
+  const metadataKind = String(workflow.asset_kind || workflow.agent_metadata?.asset_kind || workflow.agentMetadata?.assetKind || '').toLowerCase();
+  return requestedTypes.some(type => {
+    const needle = String(type).trim().toLowerCase();
+    if (!needle) return false;
+    if (metadataKind === needle || metadataKind === `${needle}s`) return true;
+    if (assetType === needle || assetType === `${needle}s`) return true;
+    return tags.some(tag => tag === needle || tag === `${needle}s` || tag.includes(needle));
+  });
+}
+
+function itemMatchesKeyword(workflow, keyword) {
+  if (!keyword) return true;
+  const needle = normalizeQuery(keyword).toLowerCase();
+  const fields = [
+    workflow.title,
+    workflow.slug,
+    workflow.description,
+    ...(workflow.tags || []).flatMap(t => [t.name, t.slug]),
+  ].filter(Boolean).join(' ').toLowerCase();
+  return needle.split(/\s+/).every(word => fields.includes(word));
+}
+
+async function fetchCloneItems(username, config, apiBase, args) {
+  const pageSize = Number(args.flags.pageSize || 200) || 200;
+  const keyword = args.flags.keyword || '';
+  const requestedTypes = String(args.flags.types || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+
+  let effectiveUsername = username.startsWith('@') ? username.slice(1) : username;
+  const result = { username: effectiveUsername, source: 'public', list: [], total: 0 };
+
+  let cloneSelf = effectiveUsername === 'me';
+  if (config?.token) {
+    try {
+      const me = await apiRequest('GET', '/api/v1/tokenboard/auth/me', null, config.token, apiBase);
+      if (effectiveUsername === 'me' || me.nickname?.toLowerCase() === effectiveUsername.toLowerCase()) {
+        cloneSelf = true;
+        effectiveUsername = me.nickname || effectiveUsername;
+        result.username = effectiveUsername;
+      }
+    } catch { /* anonymous/public clone still works */ }
+  }
+
+  if (cloneSelf) {
+    if (!config?.token) error('Cloning @me requires login or TOKREPO_TOKEN.');
+    let page = 1;
+    while (true) {
+      const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/my?page=${page}&page_size=${pageSize}`, null, config.token, apiBase);
+      const items = data.list || [];
+      result.total = data.total || result.total;
+      result.list.push(...items);
+      if (items.length < pageSize || result.list.length >= result.total) break;
+      page++;
+    }
+    result.source = 'my';
+  } else {
+    let page = 1;
+    while (true) {
+      const params = [
+        `author_name=${encodeURIComponent(effectiveUsername)}`,
+        `page=${page}`,
+        `page_size=${pageSize}`,
+        'sort_by=latest',
+      ];
+      if (keyword) params.push(`keyword=${encodeURIComponent(normalizeQuery(keyword))}`);
+      const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?${params.join('&')}`, null, config?.token, apiBase);
+      const items = data.list || data.items || [];
+      result.total = data.total || result.total;
+      result.list.push(...items);
+      if (items.length < pageSize || result.list.length >= result.total) break;
+      page++;
+    }
+  }
+
+  result.list = result.list.filter(item => itemMatchesKeyword(item, keyword) && tagMatchesTypes(item, requestedTypes));
+  result.count = result.list.length;
+  result.keyword = keyword || undefined;
+  result.types = requestedTypes;
+  return result;
+}
+
 async function cmdClone() {
-  const target = process.argv[3];
-  if (!target) error('Usage: tokrepo clone @username');
+  const args = parseArgs(process.argv);
+  const target = args.positional[0];
+  if (!target) {
+    showCloneHelp();
+    process.exit(1);
+  }
 
-  log(`\n${C.bold}tokrepo clone${C.reset}\n`);
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo clone${C.reset}\n`);
 
   const config = readConfig();
   const apiBase = config?.api || DEFAULT_API;
+  const targetTool = validateInstallTarget(args.flags.target);
+  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
 
-  // Extract username from @username format
-  let username = target;
-  if (username.startsWith('@')) username = username.slice(1);
-
-  // Step 1: Find user's UUID by searching for their workflows
-  info(`Finding user @${username}...`);
-  let authorUuid = '';
   try {
-    const searchData = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?keyword=${encodeURIComponent(username)}&page=1&page_size=5&sort_by=latest`, null, config?.token, apiBase);
-    const items = searchData.list || searchData.items || [];
-    for (const item of items) {
-      const authorName = (item.author?.nickname || item.nickname || '').toLowerCase();
-      if (authorName === username.toLowerCase()) {
-        authorUuid = item.author?.uuid || item.author_uuid || '';
-        break;
+    if (!json) info(`Fetching assets from ${target}...`);
+    const cloneItems = await fetchCloneItems(target, config, apiBase, args);
+
+    if (cloneItems.list.length === 0) {
+      if (json) {
+        outputJson({ target, count: 0, list: [] });
+      } else {
+        info(`${target} has no matching assets.`);
       }
+      return;
     }
-  } catch { /* fall through */ }
 
-  if (!authorUuid) {
-    // Try fetching user's own workflows if logged in and cloning self
-    if (config?.token) {
+    if (!json) log(`  Found ${C.bold}${cloneItems.list.length}${C.reset} matching asset(s)\n`);
+
+    if (targetTool === 'codex') {
+      const results = [];
+      let installedCount = 0;
+      for (let i = 0; i < cloneItems.list.length; i++) {
+        const item = cloneItems.list[i];
+        if (!json) log(`${C.dim}[${i + 1}/${cloneItems.list.length}]${C.reset} ${item.title}`);
+        try {
+          const detail = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${item.uuid}`, null, config?.token, apiBase);
+          const workflow = detail.workflow;
+          const assetType = getWorkflowAssetType(workflow);
+          const contents = extractInstallableContents(workflow, assetType);
+          if (contents.length === 0) throw new Error('No installable content found');
+          const result = await installCodexAsset(workflow, contents, {
+            ...args.flags,
+            dryRun,
+            stage: Boolean(args.flags.stage),
+            approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+            json: true,
+            throwOnError: true,
+          });
+          if (!dryRun) installedCount += result.installedFiles.length;
+          results.push({
+            uuid: workflow.uuid,
+            title: workflow.title,
+            dryRun: Boolean(dryRun || args.flags.stage),
+            staged: Boolean(result.staged),
+            stagePath: result.stagePath,
+            installMode: result.plan.installMode,
+            files: result.plan.files,
+            installedFiles: result.installedFiles || [],
+            risks: result.plan.risks,
+          });
+          if (!json) {
+            const fileCount = (dryRun || args.flags.stage) ? result.plan.files.length : result.installedFiles.length;
+            success(`${args.flags.stage ? 'Staged' : dryRun ? 'Planned' : 'Installed'} ${fileCount} file(s)`);
+          }
+        } catch (e) {
+          results.push({ uuid: item.uuid, title: item.title, error: e.message });
+          if (!json) warn(`Skipped "${item.title}": ${e.message}`);
+        }
+      }
+
+      const response = {
+        target,
+        username: cloneItems.username,
+        targetTool: 'codex',
+        dryRun,
+        total: cloneItems.total,
+        count: cloneItems.count,
+        manifestPath: CODEX_MANIFEST_FILE,
+        results,
+      };
+    if (json) {
+        outputJson(response);
+      } else {
+        log('');
+        if (args.flags.stage) {
+          success(`Staged ${results.filter(r => !r.error).length}/${cloneItems.list.length} asset install plan(s)`);
+        } else if (dryRun) {
+          success(`Dry run complete: ${results.filter(r => !r.error).length}/${cloneItems.list.length} assets planned`);
+        } else {
+          success(`Installed ${installedCount} Codex file(s) from ${results.filter(r => !r.error).length}/${cloneItems.list.length} assets`);
+          log(`  ${C.dim}Manifest: ${CODEX_MANIFEST_FILE}${C.reset}\n`);
+        }
+      }
+      return;
+    }
+
+    if (targetTool && targetTool !== 'codex') {
+      error(`clone --target ${targetTool} is not implemented yet. Supported clone target: codex`);
+    }
+
+    if (json) {
+      outputJson(cloneItems);
+      return;
+    }
+
+    // Legacy raw clone behavior for users who do not specify a target.
+    const outDir = path.join(process.cwd(), cloneItems.username);
+    if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+
+    let downloaded = 0;
+    for (const item of cloneItems.list) {
+      const title = item.title || item.uuid;
+      const safeDirName = title.replace(/[/\\?%*:|"<>]/g, '-').substring(0, 80);
+      const assetDir = path.join(outDir, safeDirName);
+
       try {
-        const me = await apiRequest('GET', '/api/v1/tokenboard/auth/me', null, config.token, apiBase);
-        if (me.nickname?.toLowerCase() === username.toLowerCase()) {
-          authorUuid = me.uuid;
+        const detail = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${item.uuid}`, null, config?.token, apiBase);
+        const workflow = detail.workflow;
+        const contents = extractInstallableContents(workflow, getWorkflowAssetType(workflow));
+
+        if (contents.length > 0) {
+          if (!fs.existsSync(assetDir)) fs.mkdirSync(assetDir, { recursive: true });
+          for (const contentItem of contents) {
+            const safeName = sanitizeRelativePath(contentItem.name || 'content.md');
+            fs.writeFileSync(path.join(assetDir, safeName), contentItem.content);
+          }
+          downloaded++;
+          log(`  ${C.green}✓${C.reset} ${safeDirName} ${C.dim}(${contents.length} files)${C.reset}`);
         }
-      } catch { /* fall through */ }
+      } catch (e) {
+        log(`  ${C.yellow}!${C.reset} ${safeDirName} ${C.dim}(skipped: ${e.message})${C.reset}`);
+      }
     }
-    if (!authorUuid) error(`User @${username} not found. Make sure they have published assets.`);
+
+    log('');
+    success(`Cloned ${downloaded}/${cloneItems.list.length} assets to ./${cloneItems.username}/`);
+  } catch (e) {
+    error(`Clone failed: ${e.message}`);
+  }
+}
+
+function currentFileSha(filePath) {
+  try {
+    return sha256(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return '';
+  }
+}
+
+function diffCodexPlanWithLocal(plan, manifestRecord = {}) {
+  const reasons = [];
+  const desired = new Map(plan.files.map(file => [file.path, file.sha256]));
+  const recordedFiles = manifestRecord.installedFiles || manifestRecord.installed_files || [];
+
+  for (const file of plan.files) {
+    if (!fs.existsSync(file.path)) {
+      reasons.push({ type: 'missing', path: file.path });
+      continue;
+    }
+    const actualSha = currentFileSha(file.path);
+    if (actualSha !== file.sha256) {
+      reasons.push({ type: 'changed', path: file.path, actualSha, expectedSha: file.sha256 });
+    }
+  }
+
+  for (const file of recordedFiles) {
+    if (file.path && !desired.has(file.path)) {
+      reasons.push({ type: 'obsolete-manifest-path', path: file.path });
+    }
+  }
+
+  return {
+    needsUpdate: reasons.length > 0,
+    reasons,
+  };
+}
+
+async function fetchWorkflowForInstall(uuid, config, apiBase) {
+  const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${encodeURIComponent(uuid)}`, null, config?.token, apiBase);
+  const workflow = data.workflow;
+  const contents = extractInstallableContents(workflow, getWorkflowAssetType(workflow));
+  if (contents.length === 0) {
+    throw new Error('No installable content found');
+  }
+  return { workflow, contents };
+}
+
+async function cmdSyncInstalled() {
+  const args = parseArgs(process.argv);
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') {
+    error(`sync-installed currently supports --target codex only`);
+  }
+
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo sync-installed${C.reset}\n`);
+
+  const manifest = readCodexManifest();
+  const installed = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  const dryRun = Boolean(args.flags.dryRun || args.flags.dry_run);
+  const stage = Boolean(args.flags.stage);
+  if (installed.length === 0) {
+    if (json) outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, dryRun, stage, count: 0, results: [] });
+    else info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
+    return;
   }
 
-  // Step 2: List all public workflows by this author
-  info(`Fetching all assets by @${username}...`);
-  let allItems = [];
-  let page = 1;
-  while (true) {
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+  const force = Boolean(args.flags.update || args.flags.force || args.flags.all);
+  const results = [];
+
+  for (let i = 0; i < installed.length; i++) {
+    const record = installed[i];
+    const uuid = record.uuid;
+    if (!uuid) continue;
+
+    if (!json) log(`${C.dim}[${i + 1}/${installed.length}]${C.reset} ${record.title || uuid}`);
+
     try {
-      const data = await apiRequest('GET', `/api/v1/tokenboard/workflows/list?author_uuid=${authorUuid}&page=${page}&page_size=50&sort_by=latest`, null, config?.token, apiBase);
-      const items = data.list || data.items || [];
-      if (items.length === 0) break;
-      allItems = allItems.concat(items);
-      if (items.length < 50) break;
-      page++;
+      const { workflow, contents } = await fetchWorkflowForInstall(uuid, config, apiBase);
+      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode });
+      const diff = diffCodexPlanWithLocal(plan, record);
+      const shouldWrite = force || diff.needsUpdate;
+
+      if (dryRun) {
+        results.push({
+          uuid,
+          title: workflow.title,
+          status: shouldWrite ? 'would-update' : 'unchanged',
+          needsUpdate: shouldWrite,
+          reasons: diff.reasons,
+          plan: publicInstallPlan(plan),
+        });
+        if (!json) {
+          const label = shouldWrite ? `${C.yellow}would update${C.reset}` : `${C.green}unchanged${C.reset}`;
+          log(`  ${label}`);
+        }
+        continue;
+      }
+
+      if (!shouldWrite) {
+        results.push({
+          uuid,
+          title: workflow.title,
+          status: 'unchanged',
+          needsUpdate: false,
+          reasons: [],
+        });
+        if (!json) success('Unchanged');
+        continue;
+      }
+
+      const installResult = await installCodexAsset(workflow, contents, {
+        ...args.flags,
+        dryRun: false,
+        stage,
+        installMode: record.installMode || record.install_mode,
+        approveMcp: Boolean(args.flags.approveMcp || args.flags.approve_mcp),
+        json: true,
+        throwOnError: true,
+      });
+
+      results.push({
+        uuid,
+        title: workflow.title,
+        status: stage ? 'staged' : 'updated',
+        needsUpdate: true,
+        reasons: diff.reasons,
+        stagePath: installResult.stagePath,
+        installedFiles: installResult.installedFiles || [],
+        plan: installResult.plan,
+      });
+      if (!json) success(stage ? `Staged ${installResult.plan.files.length} file(s)` : `Updated ${(installResult.installedFiles || []).length} file(s)`);
     } catch (e) {
-      error(`Failed to list assets: ${e.message}`);
+      results.push({ uuid, title: record.title || uuid, status: 'failed', error: e.message });
+      if (!json) warn(`Failed: ${e.message}`);
     }
   }
 
-  if (allItems.length === 0) {
-    info(`@${username} has no public assets.`);
+  const summary = {
+    targetTool: 'codex',
+    manifestPath: CODEX_MANIFEST_FILE,
+    dryRun,
+    stage,
+    count: results.length,
+    updated: results.filter(item => item.status === 'updated').length,
+    staged: results.filter(item => item.status === 'staged').length,
+    unchanged: results.filter(item => item.status === 'unchanged').length,
+    failed: results.filter(item => item.status === 'failed').length,
+    results,
+  };
+
+  if (json) {
+    outputJson(summary);
+  } else {
+    log('');
+    success(`Sync complete: ${summary.updated} updated, ${summary.staged} staged, ${summary.unchanged} unchanged, ${summary.failed} failed`);
+  }
+}
+
+async function cmdInstalled() {
+  const args = parseArgs(process.argv);
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`installed currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo installed${C.reset}\n`);
+
+  const manifest = readCodexManifest();
+  const records = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  const list = records.map(record => {
+    const files = (record.installedFiles || record.installed_files || []).map(file => {
+      const actualSha = file.path && fs.existsSync(file.path) ? currentFileSha(file.path) : '';
+      return {
+        path: file.path,
+        sourceName: file.sourceName || file.source_name,
+        sha256: file.sha256,
+        exists: Boolean(file.path && fs.existsSync(file.path)),
+        changed: Boolean(actualSha && file.sha256 && actualSha !== file.sha256),
+      };
+    });
+    return {
+      uuid: record.uuid,
+      title: record.title,
+      sourceUrl: record.sourceUrl || record.source_url,
+      targetTool: 'codex',
+      installMode: record.installMode || record.install_mode,
+      installedAt: record.installedAt || record.installed_at,
+      contentHash: record.contentHash || record.content_hash || '',
+      risks: record.risks || [],
+      files,
+      status: files.some(file => !file.exists) ? 'missing-files' : files.some(file => file.changed) ? 'local-changes' : 'installed',
+    };
+  });
+
+  if (json) {
+    outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, count: list.length, list });
+    return;
+  }
+
+  if (list.length === 0) {
+    info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
     return;
   }
 
-  log(`  Found ${C.bold}${allItems.length}${C.reset} assets\n`);
+  for (const item of list) {
+    const color = item.status === 'installed' ? C.green : C.yellow;
+    log(`  ${color}${item.status}${C.reset}  ${C.bold}${item.title || item.uuid}${C.reset}`);
+    log(`  ${C.dim}${item.uuid} · ${item.installMode || 'unknown'} · ${item.files.length} file(s)${C.reset}\n`);
+  }
+}
+
+async function cmdOutdated() {
+  const args = parseArgs(process.argv);
+  const targetTool = validateInstallTarget(args.flags.target || 'codex');
+  if (targetTool !== 'codex') error(`outdated currently supports --target codex only`);
+
+  const json = Boolean(args.flags.json);
+  if (!json) log(`\n${C.bold}tokrepo outdated${C.reset}\n`);
 
-  // Step 3: Create directory and pull each asset
-  const outDir = path.join(process.cwd(), username);
-  if (!fs.existsSync(outDir)) {
-    fs.mkdirSync(outDir, { recursive: true });
+  const manifest = readCodexManifest();
+  const installed = (manifest.installs || []).filter(item => (item.targetTool || item.target_tool) === 'codex');
+  if (installed.length === 0) {
+    if (json) outputJson({ targetTool: 'codex', count: 0, outdated: 0, list: [] });
+    else info(`No Codex installs found in ${CODEX_MANIFEST_FILE}`);
+    return;
   }
 
-  let downloaded = 0;
-  for (const item of allItems) {
-    const title = item.title || item.uuid;
-    const safeDirName = title.replace(/[/\\?%*:|"<>]/g, '-').substring(0, 80);
-    const assetDir = path.join(outDir, safeDirName);
+  const config = readConfig();
+  const apiBase = config?.api || DEFAULT_API;
+  const list = [];
+  let unchanged = 0;
+  let failed = 0;
 
+  for (const record of installed) {
     try {
-      const detail = await apiRequest('GET', `/api/v1/tokenboard/workflows/detail?uuid=${item.uuid}`, null, config?.token, apiBase);
-      const workflow = detail.workflow;
-
-      if (workflow.steps && workflow.steps.length > 0) {
-        if (!fs.existsSync(assetDir)) fs.mkdirSync(assetDir, { recursive: true });
-        for (const step of workflow.steps) {
-          const content = step.prompt_template || step.promptTemplate;
-          if (content) {
-            const fileName = `${step.title || 'step-' + step.step_order}`;
-            const safeName = fileName.replace(/[/\\?%*:|"<>]/g, '-');
-            fs.writeFileSync(path.join(assetDir, safeName), content);
-          }
-        }
-        downloaded++;
-        log(`  ${C.green}✓${C.reset} ${safeDirName} ${C.dim}(${workflow.steps.length} files)${C.reset}`);
+      const { workflow, contents } = await fetchWorkflowForInstall(record.uuid, config, apiBase);
+      const plan = buildCodexInstallPlan(workflow, contents, { installMode: record.installMode || record.install_mode });
+      const diff = diffCodexPlanWithLocal(plan, record);
+      if (diff.needsUpdate) {
+        list.push({
+          uuid: record.uuid,
+          title: workflow.title,
+          status: 'outdated',
+          reasons: diff.reasons,
+          plan: publicInstallPlan(plan),
+        });
+      } else {
+        unchanged++;
       }
     } catch (e) {
-      log(`  ${C.yellow}!${C.reset} ${safeDirName} ${C.dim}(skipped: ${e.message})${C.reset}`);
+      failed++;
+      list.push({ uuid: record.uuid, title: record.title || record.uuid, status: 'failed', error: e.message });
     }
   }
 
+  if (json) {
+    outputJson({ targetTool: 'codex', manifestPath: CODEX_MANIFEST_FILE, count: installed.length, outdated: list.filter(i => i.status === 'outdated').length, unchanged, failed, list });
+    return;
+  }
+
+  const outdated = list.filter(item => item.status === 'outdated');
+  if (outdated.length === 0 && failed === 0) {
+    success(`All ${unchanged} Codex install(s) are up to date.`);
+    return;
+  }
+  for (const item of list) {
+    if (item.status === 'failed') {
+      warn(`${item.title}: ${item.error}`);
+    } else {
+      log(`  ${C.yellow}outdated${C.reset}  ${C.bold}${item.title}${C.reset}`);
+      for (const reason of item.reasons.slice(0, 3)) {
+        log(`    ${C.dim}${reason.type}: ${reason.path || ''}${C.reset}`);
+      }
+    }
+  }
   log('');
-  success(`Cloned ${downloaded}/${allItems.length} assets to ./${username}/`);
+  info(`Run ${C.cyan}tokrepo update --target codex --all${C.reset} to update installed Codex assets.`);
 }
 
 async function cmdTags() {
@@ -1453,19 +2545,24 @@ ${C.bold}USAGE${C.reset}
 
 ${C.bold}DISCOVER & INSTALL${C.reset}
   ${C.cyan}search${C.reset} <query>      Search assets by keyword
+  ${C.cyan}detail${C.reset} <name|uuid>  Show full asset metadata
   ${C.cyan}install${C.reset} <name|uuid> Smart install (auto-detects type & placement)
   ${C.cyan}pull${C.reset} <url|uuid|@u/n> Download raw asset files
   ${C.cyan}clone${C.reset} @username      Clone all assets from a user
+  ${C.cyan}installed${C.reset}            List installed Codex assets from manifest
+  ${C.cyan}outdated${C.reset}             Check installed Codex assets for updates
+  ${C.cyan}sync-installed${C.reset}       Update installed Codex assets from manifest
 
 ${C.bold}PUBLISH${C.reset}
   ${C.cyan}push${C.reset} [files...]     Push files/directory (idempotent upsert)
   ${C.cyan}status${C.reset}              Compare local vs remote (like git status)
   ${C.cyan}init${C.reset}                Create .tokrepo.json project config
-  ${C.cyan}update${C.reset} <uuid> [f]   Update existing asset
+  ${C.cyan}update${C.reset} <uuid> [f]   Update existing remote asset
+  ${C.cyan}update${C.reset} --target codex --all   Update installed Codex assets
   ${C.cyan}delete${C.reset} <uuid>       Delete an asset
 
 ${C.bold}ACCOUNT${C.reset}
-  ${C.cyan}login${C.reset}               Save API token (or set TOKREPO_TOKEN env var)
+  ${C.cyan}login${C.reset}               Save API key (or set TOKREPO_TOKEN env var)
   ${C.cyan}list${C.reset}                List your published assets
   ${C.cyan}tags${C.reset}                List available tags
   ${C.cyan}whoami${C.reset}              Show current user
@@ -1477,10 +2574,14 @@ ${C.bold}PUSH OPTIONS${C.reset}
   ${C.cyan}--title${C.reset} "..."       Set title (auto-detected from README or dir name)
   ${C.cyan}--desc${C.reset} "..."        Set description
   ${C.cyan}--tag${C.reset} Skills        Add tag (repeatable)
+  ${C.cyan}--kind${C.reset} skill         Set agent asset_kind
+  ${C.cyan}--target${C.reset} codex       Add target tool metadata on push
+  ${C.cyan}--install-mode${C.reset} bundle Set install_mode metadata
 
 ${C.bold}INSTALL BEHAVIOR${C.reset}
   Skills   → .claude/skills/    (if .claude/ exists)
   Gemini   → .gemini/GEMINI.md  (with --target gemini)
+  Codex    → ~/.codex/skills/    (with --target codex)
   Scripts  → current dir        (chmod +x)
   Configs  → project root
   MCP      → current dir        (.json)
@@ -1488,9 +2589,18 @@ ${C.bold}INSTALL BEHAVIOR${C.reset}
 
 ${C.bold}EXAMPLES${C.reset}
   tokrepo search "mcp server"                 # Find MCP configs
+  tokrepo search video --json                 # Machine-readable search
+  tokrepo detail ca000374-f5d8-... --json     # Machine-readable detail
   tokrepo install ca000374-f5d8-...           # Install by UUID
+  tokrepo install ca000374-f5d8-... --target codex
   tokrepo install c4b18aeb --target gemini    # Install for Gemini CLI
+  tokrepo clone @henuwangkai --target codex --keyword video
+  tokrepo installed --target codex --json
+  tokrepo outdated --target codex --json
+  tokrepo update --target codex --all
+  tokrepo sync-installed --target codex --dry-run
   tokrepo push --private my-rules.md          # Save one file privately
+  tokrepo push . --kind skill --target codex --install-mode bundle
   tokrepo push --public skill.md              # Share one file publicly
   tokrepo push --private .                    # Push current dir as private
   tokrepo push --public --title "My MCP" .    # Push dir publicly with title
@@ -1511,10 +2621,141 @@ ${C.bold}GET YOUR TOKEN${C.reset}
 `);
 }
 
+function showSearchHelp() {
+  log(`
+${C.bold}tokrepo search${C.reset}
+
+USAGE
+  tokrepo search <query> [--json] [--all] [--page-size N] [--sort-by views|latest|stars|popular]
+
+EXAMPLES
+  tokrepo search video
+  tokrepo search video --json
+  tokrepo search "mcp server" --json --all
+`);
+}
+
+function showDetailHelp() {
+  log(`
+${C.bold}tokrepo detail${C.reset}
+
+USAGE
+  tokrepo detail <uuid|url|name> [--json]
+
+EXAMPLES
+  tokrepo detail 91aeb22d-eff0-4310-abc6-811d2394b420 --json
+  tokrepo detail https://tokrepo.com/en/workflows/91aeb22d-eff0-4310-abc6-811d2394b420
+`);
+}
+
+function showInstallHelp() {
+  log(`
+${C.bold}tokrepo install${C.reset}
+
+USAGE
+  tokrepo install <uuid|url|name|pack/slug> [--target gemini|codex] [--yes] [--dry-run] [--stage] [--approve-mcp] [--json]
+
+TARGETS
+  codex    Write Codex skills to ~/.codex/skills/<asset-slug>/SKILL.md
+  gemini   Write project instructions to .gemini/GEMINI.md
+
+EXAMPLES
+  tokrepo install awesome-cursor-rules
+  tokrepo install ca000374-f5d8-4d75-a30c-460fda0b6b0e
+  tokrepo install https://tokrepo.com/en/workflows/ca000374-...
+  tokrepo install 91aeb22d-eff0-4310-abc6-811d2394b420 --target codex
+  tokrepo install 91aeb22d-eff0-4310-abc6-811d2394b420 --target codex --dry-run --json
+  tokrepo install 20bc3ffd-1d7a-41d1-86d0-b668e8500cee --target codex --stage
+  tokrepo install c4b18aeb --target gemini
+`);
+}
+
+function showListHelp() {
+  log(`
+${C.bold}tokrepo list${C.reset}
+
+USAGE
+  tokrepo list [--json] [--all] [--page-size N]
+
+EXAMPLES
+  tokrepo list
+  tokrepo list --json --all
+`);
+}
+
+function showCloneHelp() {
+  log(`
+${C.bold}tokrepo clone${C.reset}
+
+USAGE
+  tokrepo clone @username [--target codex] [--keyword query] [--types skill,prompt,knowledge] [--dry-run] [--stage] [--approve-mcp] [--json] [--manifest]
+
+EXAMPLES
+  tokrepo clone @henuwangkai --target codex --types skill,prompt,knowledge
+  tokrepo clone @henuwangkai --target codex --keyword video
+  tokrepo clone @me --target codex --dry-run --json --manifest
+`);
+}
+
+function showSyncInstalledHelp() {
+  log(`
+${C.bold}tokrepo sync-installed${C.reset}
+
+USAGE
+  tokrepo sync-installed --target codex [--dry-run] [--stage] [--update] [--approve-mcp] [--json]
+  tokrepo installed --target codex [--json]
+  tokrepo outdated --target codex [--json]
+  tokrepo update --target codex --all [--stage] [--approve-mcp] [--json]
+
+BEHAVIOR
+  Reads ~/.codex/tokrepo/install-manifest.json, fetches each TokRepo asset again,
+  rebuilds the Codex install plan, compares local files by sha256, then updates
+  changed or missing files. Use --update to force reinstall unchanged assets.
+
+EXAMPLES
+  tokrepo installed --target codex --json
+  tokrepo outdated --target codex --json
+  tokrepo update --target codex --all
+  tokrepo sync-installed --target codex --dry-run --json
+  tokrepo sync-installed --target codex --stage
+  tokrepo sync-installed --target codex --update --approve-mcp
+`);
+}
+
+function showCommandHelp(command) {
+  switch (command) {
+    case 'search':
+    case 'find':
+      showSearchHelp(); break;
+    case 'detail':
+      showDetailHelp(); break;
+    case 'install':
+    case 'i':
+      showInstallHelp(); break;
+    case 'list':
+      showListHelp(); break;
+    case 'clone':
+      showCloneHelp(); break;
+    case 'sync-installed':
+    case 'sync':
+    case 'installed':
+    case 'outdated':
+      showSyncInstalledHelp(); break;
+    default:
+      showHelp(); break;
+  }
+}
+
 // ─── Main ───
 
 async function main() {
   const command = process.argv[2];
+  const args = parseArgs(process.argv);
+
+  if (args.flags.help && command && !['help', '--help', '-h'].includes(command)) {
+    showCommandHelp(command);
+    return;
+  }
 
   switch (command) {
     case 'login': await cmdLogin(); break;
@@ -1522,11 +2763,15 @@ async function main() {
     case 'push': await cmdPush(); break;
     case 'pull': await cmdPull(); break;
     case 'search': case 'find': await cmdSearch(); break;
+    case 'detail': await cmdDetail(); break;
     case 'install': case 'i': await cmdInstall(); break;
     case 'list': await cmdList(); break;
     case 'update': await cmdUpdate(); break;
     case 'delete': await cmdDelete(); break;
     case 'clone': await cmdClone(); break;
+    case 'installed': await cmdInstalled(); break;
+    case 'outdated': await cmdOutdated(); break;
+    case 'sync-installed': case 'sync': await cmdSyncInstalled(); break;
     case 'tags': await cmdTags(); break;
     case 'status': case 'diff': await cmdStatus(); break;
     case 'whoami': await cmdWhoami(); break;
@@ -1539,7 +2784,9 @@ async function main() {
   }
 
   // Non-blocking update check after command completes
-  checkForUpdate();
+  if (!wantsJson(process.argv) && !args.flags.help) {
+    checkForUpdate();
+  }
 }
 
 main().catch((e) => { error(e.message); });