@agent-native/core 0.32.18 → 0.35.0

package/dist/cli/context-xray-local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-xray-local.js","sourceRoot":"","sources":["../../src/cli/context-xray-local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAiB7B,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgkBzC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DpC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCtC,CAAC;AAEF,SAAS,SAAS;IAChB,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,OAAe;IACpD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACzC,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,OAAe,EAAE,OAAiB;IACjE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,uBAAuB,CAAC,OAAe,EAAE,OAAiB;IACjE,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,CAAC,EACnE,qBAAqB,EACrB,OAAO,CACR,CAAC;IACF,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,CAAC,EAC5D,uBAAuB,EACvB,OAAO,CACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAAuC;IAEvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;IAC5E,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACzE,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO;YACL,QAAQ,EAAE,CAAC,qBAAqB,CAAC;YACjC,UAAU;YACV,OAAO;SACR,CAAC;IACJ,CAAC;IAED,eAAe,CAAC,UAAU,EAAE,uBAAuB,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,GAAG,OAAO,MAAM,CAAC;QACjC,eAAe,CACb,OAAO,EACP,qBAAqB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,SAAS,CACzD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;SAAM,CAAC;QACN,eAAe,CACb,OAAO,EACP,2BAA2B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,SAAS,CAC/D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,WAAW,GACf,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACnD,uBAAuB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,CAAC,EAC5D,qBAAqB,EACrB,OAAO,CACR,CAAC;QACF,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,UAAU,EAAE,iBAAiB,CAAC,EACrD,uBAAuB,EACvB,OAAO,CACR,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,WAAW,EAAE,CAAC;QAC/C,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,CAAC,EACxE,qBAAqB,EACrB,OAAO,CACR,CAAC;QACF,SAAS,CACP,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,CAAC,EACjE,uBAAuB,EACvB,OAAO,CACR,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,CAAC,qBAAqB,CAAC;QACjC,UAAU;QACV,OAAO;KACR,CAAC;AACJ,CAAC","sourcesContent":["import fs from \"node:fs\";\nimport os from \"node:os\";\nimport path from \"node:path\";\n\nimport type { ClientId } from \"./mcp-config-writers.js\";\n\nexport interface InstallLocalContextXrayOptions {\n  baseDir?: string;\n  clients: ClientId[];\n  scope: string;\n  dryRun?: boolean;\n}\n\nexport interface InstallLocalContextXrayResult {\n  commands: string[];\n  scriptPath: string;\n  written: string[];\n}\n\nconst CONTEXT_XRAY_EXECUTABLE = String.raw`#!/usr/bin/env node\n\"use strict\";\n\nconst childProcess = require(\"node:child_process\");\nconst fs = require(\"node:fs\");\nconst os = require(\"node:os\");\nconst path = require(\"node:path\");\nconst { pathToFileURL } = require(\"node:url\");\n\nconst HOME = os.homedir();\nconst CODEX_DIR = process.env.CODEX_HOME && process.env.CODEX_HOME.trim() ? process.env.CODEX_HOME.trim() : path.join(HOME, \".codex\");\nconst CLAUDE_DIR = path.join(HOME, \".claude\");\nconst OUT_DIR = path.join(CODEX_DIR, \"context-xray\");\nconst SESSION_ID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;\nconst CATEGORIES = [\"user\", \"assistant\", \"tool_call\", \"tool_output\", \"reasoning\", \"instructions\", \"attachment\", \"metadata\", \"other\"];\nconst LABELS = {\n  user: \"User asks\",\n  assistant: \"Assistant text\",\n  tool_call: \"Tool calls\",\n  tool_output: \"Tool output\",\n  reasoning: \"Reasoning\",\n  instructions: \"Instructions/context\",\n  attachment: \"Attachments\",\n  metadata: \"Metadata\",\n  other: \"Other\",\n};\nconst COLORS = {\n  user: \"#8ba8ff\",\n  assistant: \"#55b982\",\n  tool_call: \"#f0a85b\",\n  tool_output: \"#e06b73\",\n  reasoning: \"#a77be8\",\n  instructions: \"#6ac3d5\",\n  attachment: \"#d6a85a\",\n  metadata: \"#9aa3ad\",\n  other: \"#c3c8ce\",\n};\n\nfunction parseArgs(argv) {\n  const out = {\n    mode: \"current\",\n    source: \"both\",\n    since: \"7d\",\n    last: 12,\n    scanLimit: 80,\n    project: process.cwd(),\n    allProjects: false,\n    sessionId: \"\",\n    format: \"html\",\n    out: \"\",\n    open: false,\n    port: 0,\n  };\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    const eat = (flag) => {\n      if (arg === flag) return argv[++i] || \"\";\n      if (arg.startsWith(flag + \"=\")) return arg.slice(flag.length + 1);\n      return undefined;\n    };\n    let value;\n    if (arg === \"threads\" || arg === \"--threads\") out.mode = \"threads\";\n    else if (arg === \"trends\" || arg === \"--trends\") out.mode = \"trends\";\n    else if (arg === \"current\" || arg === \"--current\") out.mode = \"current\";\n    else if ((value = eat(\"--source\")) !== undefined) out.source = value;\n    else if ((value = eat(\"--since\")) !== undefined) out.since = value;\n    else if ((value = eat(\"--last\")) !== undefined) out.last = Number(value) || out.last;\n    else if ((value = eat(\"--scan-limit\")) !== undefined) out.scanLimit = Number(value) || out.scanLimit;\n    else if ((value = eat(\"--project\")) !== undefined) out.project = value;\n    else if ((value = eat(\"--session-id\")) !== undefined) out.sessionId = value;\n    else if ((value = eat(\"--format\")) !== undefined) out.format = value;\n    else if ((value = eat(\"--out\")) !== undefined) out.out = value;\n    else if ((value = eat(\"--port\")) !== undefined) out.port = Number(value) || 0;\n    else if (arg === \"--all-projects\") out.allProjects = true;\n    else if (arg === \"--open\") out.open = true;\n    else if (arg === \"--json\") out.format = \"json\";\n    else if (arg === \"--help\" || arg === \"-h\") out.help = true;\n  }\n  if (process.env.CLAUDE_CODE_SESSION_ID && !out.sessionId && out.mode === \"current\") {\n    out.sessionId = process.env.CLAUDE_CODE_SESSION_ID;\n  }\n  if (out.mode === \"threads\") {\n    out.allProjects = true;\n    out.last = Math.max(out.last, 30);\n  }\n  if (out.mode === \"trends\") {\n    out.allProjects = true;\n    out.last = Math.max(out.last, 60);\n  }\n  if (out.mode === \"current\") {\n    out.last = 1;\n  }\n  return out;\n}\n\nfunction help() {\n  console.log([\n    \"Context X-Ray\",\n    \"\",\n    \"Usage:\",\n    \"  context-xray --open                    Visualize the current/recent local thread\",\n    \"  context-xray threads --open            Pick from recent Codex/Claude sessions\",\n    \"  context-xray trends --since 7d --open  Show recent usage trends\",\n    \"  context-xray --session-id <id> --open  Analyze one exact session\",\n    \"\",\n    \"Options:\",\n    \"  --source codex|claude|both\",\n    \"  --since 24h|7d|2w|ISO\",\n    \"  --last <n>\",\n    \"  --all-projects\",\n    \"  --format html|json\",\n    \"  --out <path>\",\n  ].join(\"\\n\"));\n}\n\nfunction mkdirp(dir) {\n  fs.mkdirSync(dir, { recursive: true });\n}\n\nfunction parseSince(value) {\n  const now = Date.now();\n  const match = String(value || \"7d\").trim().toLowerCase().match(/^(\\d+)([hdw])$/);\n  if (match) {\n    const amount = Number(match[1]);\n    const unit = match[2];\n    const mult = unit === \"h\" ? 3600000 : unit === \"d\" ? 86400000 : 604800000;\n    return now - amount * mult;\n  }\n  const parsed = Date.parse(value);\n  return Number.isFinite(parsed) ? parsed : now - 7 * 86400000;\n}\n\nfunction readJsonl(file) {\n  try {\n    return fs.readFileSync(file, \"utf8\").split(/\\r?\\n/).filter(Boolean).map((line) => {\n      try {\n        return JSON.parse(line);\n      } catch {\n        return null;\n      }\n    }).filter(Boolean);\n  } catch {\n    return [];\n  }\n}\n\nfunction compact(value) {\n  try {\n    const text = JSON.stringify(value);\n    return text.length > 250000 ? text.slice(0, 250000) : text;\n  } catch {\n    return String(value || \"\");\n  }\n}\n\nfunction textFrom(value, depth) {\n  if (depth > 8 || value == null) return \"\";\n  if (typeof value === \"string\") return value.length > 250000 ? value.slice(0, 250000) : value;\n  if (typeof value !== \"object\") return \"\";\n  if (Array.isArray(value)) return value.map((item) => textFrom(item, depth + 1)).filter(Boolean).join(\"\\n\");\n  const skip = new Set([\"encrypted_content\", \"id\", \"uuid\", \"call_id\", \"sessionId\", \"parentUuid\"]);\n  const keys = new Set([\"text\", \"message\", \"output\", \"result\", \"content\", \"summary\", \"arguments\", \"args\", \"input\", \"stdout\", \"stderr\", \"attachment\"]);\n  const parts = [];\n  for (const key of Object.keys(value)) {\n    if (skip.has(key)) continue;\n    const item = value[key];\n    if (keys.has(key) || typeof item === \"object\") {\n      const text = textFrom(item, depth + 1);\n      if (text) parts.push(text);\n    }\n  }\n  return parts.join(\"\\n\");\n}\n\nfunction addCounter(counter, key, amount) {\n  if (!key || !amount) return;\n  counter[key] = (counter[key] || 0) + amount;\n}\n\nfunction mergeCounter(into, from) {\n  for (const key of Object.keys(from || {})) addCounter(into, key, from[key]);\n}\n\nfunction estimateTokens(chars) {\n  return chars > 0 ? Math.max(1, Math.ceil(chars / 4)) : 0;\n}\n\nfunction fmtTokens(tokens) {\n  if (tokens >= 1000000) return (tokens / 1000000).toFixed(1) + \"m\";\n  if (tokens >= 1000) return (tokens / 1000).toFixed(1) + \"k\";\n  return String(tokens);\n}\n\nfunction pct(part, total) {\n  return total > 0 ? Math.max(0, Math.min(100, (part / total) * 100)) : 0;\n}\n\nfunction pathCounts(text) {\n  const out = {};\n  const matches = String(text || \"\").match(/(?:(?:\\/[\\w@.+,=-]+)+|(?:[\\w.-]+\\/)+[\\w.+,=-]+)(?:\\.[A-Za-z0-9_+-]+)?/g) || [];\n  for (const raw of matches) {\n    const value = raw.replace(/['\",.)]+$/g, \"\");\n    if (value.length > 5 && !value.startsWith(\"http\") && value.includes(\"/\")) addCounter(out, value, 1);\n  }\n  return out;\n}\n\nfunction codexTitle(id) {\n  const index = path.join(CODEX_DIR, \"session_index.jsonl\");\n  for (const record of readJsonl(index)) {\n    if (record.id === id && record.thread_name) return String(record.thread_name);\n  }\n  return \"\";\n}\n\nfunction observedCodexTokens(payload) {\n  if (!payload || payload.type !== \"token_count\" || !payload.info) return 0;\n  const last = payload.info.last_token_usage;\n  if (last && Number(last.total_tokens)) return Number(last.total_tokens);\n  const total = payload.info.total_token_usage;\n  if (total && Number(total.total_tokens)) return Number(total.total_tokens);\n  if (total && typeof total === \"object\") {\n    return [\"input_tokens\", \"cached_input_tokens\", \"output_tokens\", \"reasoning_output_tokens\"].reduce((sum, key) => sum + (Number(total[key]) || 0), 0);\n  }\n  return 0;\n}\n\nfunction claudeUsageTokens(usage) {\n  if (!usage || typeof usage !== \"object\") return 0;\n  return (Number(usage.input_tokens) || 0) + (Number(usage.output_tokens) || 0) + (Number(usage.cache_creation_input_tokens) || 0) + (Number(usage.cache_read_input_tokens) || 0);\n}\n\nfunction sessionIdFromPath(file) {\n  const match = path.basename(file).match(SESSION_ID_RE);\n  return match ? match[0] : path.basename(file, \".jsonl\");\n}\n\nfunction classifyCodex(record) {\n  const top = String(record.type || \"\");\n  const payload = record.payload && typeof record.payload === \"object\" ? record.payload : {};\n  const ptype = String(payload.type || \"\");\n  let category = \"other\";\n  const tools = {};\n  if (top === \"session_meta\") category = \"metadata\";\n  else if (top === \"turn_context\") category = \"instructions\";\n  else if (top === \"event_msg\") category = ptype === \"user_message\" ? \"user\" : \"metadata\";\n  else if (top === \"response_item\") {\n    if ([\"function_call\", \"custom_tool_call\", \"web_search_call\", \"tool_search_call\", \"tool_call\"].includes(ptype) || payload.name && payload.call_id) {\n      category = \"tool_call\";\n      if (payload.name) addCounter(tools, String(payload.name), 1);\n    } else if ([\"function_call_output\", \"custom_tool_call_output\", \"tool_search_output\", \"tool_result\"].includes(ptype) || Object.prototype.hasOwnProperty.call(payload, \"output\")) category = \"tool_output\";\n    else if (ptype === \"reasoning\" || payload.summary) category = \"reasoning\";\n    else if (payload.role === \"assistant\") category = \"assistant\";\n    else if (payload.role === \"user\" || payload.role === \"developer\") category = \"user\";\n  }\n  const text = textFrom(record, 0) || (category === \"metadata\" ? compact(record) : \"\");\n  return { category, chars: text.length, tools, paths: pathCounts(text) };\n}\n\nfunction classifyClaude(record) {\n  let category = \"other\";\n  const tools = {};\n  const message = record.message && typeof record.message === \"object\" ? record.message : null;\n  let text = \"\";\n  if (message) {\n    if (message.role === \"user\") category = \"user\";\n    else if (message.role === \"assistant\") category = \"assistant\";\n    const content = Array.isArray(message.content) ? message.content : [message.content];\n    const parts = [];\n    for (const part of content) {\n      if (part && typeof part === \"object\") {\n        if (part.type === \"tool_use\") {\n          category = \"tool_call\";\n          if (part.name) addCounter(tools, String(part.name), 1);\n        } else if (part.type === \"tool_result\") category = \"tool_output\";\n        else if (part.type === \"thinking\") category = \"reasoning\";\n      }\n      parts.push(textFrom(part, 0));\n    }\n    text = parts.join(\"\\n\");\n  } else if (record.toolUseResult) {\n    category = \"tool_output\";\n    text = textFrom(record.toolUseResult, 0);\n  } else if (record.attachment) {\n    category = \"attachment\";\n    text = textFrom(record.attachment, 0);\n  } else {\n    text = textFrom(record, 0);\n  }\n  return { category, chars: text.length, tools, paths: pathCounts(text) };\n}\n\nfunction summarizeCodex(file) {\n  const stat = fs.statSync(file);\n  const summary = {\n    source: \"codex\",\n    path: file,\n    sessionId: sessionIdFromPath(file),\n    title: \"\",\n    cwd: \"\",\n    startedAt: \"\",\n    updatedAt: \"\",\n    categories: {},\n    tools: {},\n    paths: {},\n    observedTokens: 0,\n    bytes: stat.size,\n    mtime: stat.mtimeMs,\n  };\n  const records = readJsonl(file);\n  for (const record of records) {\n    const payload = record.payload && typeof record.payload === \"object\" ? record.payload : {};\n    if (record.type === \"session_meta\") {\n      summary.sessionId = String(payload.id || summary.sessionId);\n      summary.cwd = String(payload.cwd || summary.cwd);\n      summary.startedAt = String(payload.timestamp || summary.startedAt);\n    }\n    if (payload.cwd && !summary.cwd) summary.cwd = String(payload.cwd);\n    if (record.timestamp) summary.updatedAt = String(record.timestamp);\n    summary.observedTokens = Math.max(summary.observedTokens, observedCodexTokens(payload));\n    const stats = classifyCodex(record);\n    addCounter(summary.categories, stats.category, stats.chars);\n    mergeCounter(summary.tools, stats.tools);\n    mergeCounter(summary.paths, stats.paths);\n  }\n  summary.title = codexTitle(summary.sessionId) || summary.sessionId;\n  return finalizeSummary(summary);\n}\n\nfunction summarizeClaude(file) {\n  const stat = fs.statSync(file);\n  const summary = {\n    source: \"claude\",\n    path: file,\n    sessionId: sessionIdFromPath(file),\n    title: \"\",\n    cwd: \"\",\n    startedAt: \"\",\n    updatedAt: \"\",\n    categories: {},\n    tools: {},\n    paths: {},\n    observedTokens: 0,\n    bytes: stat.size,\n    mtime: stat.mtimeMs,\n  };\n  const records = readJsonl(file);\n  for (const record of records) {\n    summary.sessionId = String(record.sessionId || summary.sessionId);\n    summary.cwd = String(record.cwd || summary.cwd);\n    if (record.timestamp) {\n      summary.updatedAt = String(record.timestamp);\n      if (!summary.startedAt) summary.startedAt = String(record.timestamp);\n    }\n    if (record.message && typeof record.message === \"object\") {\n      summary.observedTokens = Math.max(summary.observedTokens, claudeUsageTokens(record.message.usage));\n      if (!summary.title && record.message.role === \"user\") summary.title = cleanTitle(textFrom(record.message, 0)).slice(0, 90);\n    }\n    const stats = classifyClaude(record);\n    addCounter(summary.categories, stats.category, stats.chars);\n    mergeCounter(summary.tools, stats.tools);\n    mergeCounter(summary.paths, stats.paths);\n  }\n  if (!summary.title) summary.title = summary.sessionId;\n  return finalizeSummary(summary);\n}\n\nfunction finalizeSummary(summary) {\n  const totalChars = Object.values(summary.categories).reduce((sum, value) => sum + value, 0);\n  summary.totalChars = totalChars;\n  summary.tokens = summary.observedTokens || estimateTokens(totalChars);\n  summary.tokenMethod = summary.observedTokens ? \"observed\" : \"estimated\";\n  return summary;\n}\n\nfunction walk(root) {\n  const out = [];\n  if (!fs.existsSync(root)) return out;\n  const visit = (dir) => {\n    let entries = [];\n    try {\n      entries = fs.readdirSync(dir, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      const file = path.join(dir, entry.name);\n      if (entry.isDirectory()) visit(file);\n      else if (entry.isFile() && entry.name.endsWith(\".jsonl\")) out.push(file);\n    }\n  };\n  visit(root);\n  return out;\n}\n\nfunction encodedProject(project) {\n  return path.resolve(project).replace(/\\//g, \"-\");\n}\n\nfunction pathInsideOrEqual(value, parent) {\n  const relative = path.relative(parent, value);\n  return relative === \"\" || (!!relative && !relative.startsWith(\"..\") && !path.isAbsolute(relative));\n}\n\nfunction candidateFiles(source, args) {\n  if (args.sessionId) {\n    const roots = source === \"codex\" ? [path.join(CODEX_DIR, \"sessions\"), path.join(CODEX_DIR, \"archived_sessions\")] : [path.join(CLAUDE_DIR, \"projects\")];\n    return roots.flatMap(walk).filter((file) => file.includes(args.sessionId));\n  }\n  const since = parseSince(args.since);\n  const roots = source === \"codex\" ? [path.join(CODEX_DIR, \"sessions\"), path.join(CODEX_DIR, \"archived_sessions\")] : [path.join(CLAUDE_DIR, \"projects\")];\n  const projectFragment = encodedProject(args.project);\n  const files = roots.flatMap(walk).filter((file) => {\n    let stat;\n    try {\n      stat = fs.statSync(file);\n    } catch {\n      return false;\n    }\n    if (stat.mtimeMs < since) return false;\n    if (args.allProjects || source === \"codex\") return true;\n    return file.includes(projectFragment) || file.includes(path.basename(args.project));\n  }).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);\n  return source === \"codex\" && !args.allProjects ? files : files.slice(0, args.scanLimit);\n}\n\nfunction projectMatches(session, args) {\n  if (args.allProjects || args.sessionId) return true;\n  const project = path.resolve(args.project);\n  if (session.cwd && pathInsideOrEqual(path.resolve(session.cwd), project)) return true;\n  return session.path.includes(encodedProject(project));\n}\n\nfunction collectSessions(args) {\n  const sources = args.source === \"both\" ? [\"codex\", \"claude\"] : [args.source];\n  const sessions = [];\n  for (const source of sources) {\n    for (const file of candidateFiles(source, args)) {\n      try {\n        const summary = source === \"codex\" ? summarizeCodex(file) : summarizeClaude(file);\n        if (projectMatches(summary, args)) sessions.push(summary);\n      } catch {}\n    }\n  }\n  if (args.mode === \"current\" || args.sessionId) sessions.sort((a, b) => b.mtime - a.mtime);\n  else sessions.sort((a, b) => b.tokens - a.tokens || b.mtime - a.mtime);\n  return sessions.slice(0, args.last);\n}\n\nfunction aggregate(sessions) {\n  const out = { categories: {}, tools: {}, paths: {} };\n  for (const session of sessions) {\n    mergeCounter(out.categories, session.categories);\n    mergeCounter(out.tools, session.tools);\n    mergeCounter(out.paths, session.paths);\n  }\n  return out;\n}\n\nfunction sortedEntries(counter, limit) {\n  return Object.entries(counter || {}).sort((a, b) => b[1] - a[1]).slice(0, limit);\n}\n\nfunction recommendations(sessions) {\n  if (!sessions.length) return [\"No matching sessions found. Try context-xray threads --all-projects --since 2w --open.\"];\n  const agg = aggregate(sessions);\n  const total = Object.values(agg.categories).reduce((sum, value) => sum + value, 0);\n  const tips = [];\n  const toolOutput = pct(agg.categories.tool_output || 0, total);\n  const instructions = pct(agg.categories.instructions || 0, total);\n  const assistant = pct(agg.categories.assistant || 0, total);\n  const maxSession = sessions.reduce((a, b) => a.tokens > b.tokens ? a : b);\n  if (toolOutput > 45) tips.push(\"Tool output dominates context. Prefer targeted rg/sed ranges, cap logs, and ask agents to summarize failing blocks instead of pasting full output.\");\n  if (instructions > 25) tips.push(\"Instructions are a large share. Move stable workflow rules into skills or AGENTS/CLAUDE files and keep per-turn prompts short.\");\n  if (assistant > 45) tips.push(\"Assistant prose is heavy. Ask for terse progress updates during long runs and save rationale only when it changes decisions.\");\n  if (maxSession.tokens > 80000) tips.push(\"The largest session is about \" + fmtTokens(maxSession.tokens) + \" \" + maxSession.tokenMethod + \" tokens. Compact or start a fresh handoff before another big implementation pass.\");\n  const topTool = sortedEntries(agg.tools, 1)[0];\n  if (topTool && topTool[1] > 20) tips.push(topTool[0] + \" appears \" + topTool[1] + \" times. Batch independent inspection and use parallel reads/searches.\");\n  const topPath = sortedEntries(agg.paths, 1)[0];\n  if (topPath && topPath[1] > 12) tips.push(topPath[0] + \" appears repeatedly (\" + topPath[1] + \" mentions). Pin a short role summary instead of rereading it.\");\n  return tips.length ? tips.slice(0, 6) : [\"Recent sessions look balanced. Keep using focused reads, compact after milestones, and preserve decisions in a skill or repo doc.\"];\n}\n\nfunction escapeHtml(value) {\n  return String(value || \"\").replace(/[&<>\"']/g, (ch) => ({ \"&\": \"&amp;\", \"<\": \"&lt;\", \">\": \"&gt;\", \"\\\"\": \"&quot;\", \"'\": \"&#39;\" }[ch]));\n}\n\nfunction cleanTitle(value) {\n  return String(value || \"\").replace(/<[^>]+>/g, \" \").replace(/\\s+/g, \" \").trim();\n}\n\nfunction categoryBar(categories) {\n  const total = Object.values(categories || {}).reduce((sum, value) => sum + value, 0);\n  if (!total) return \"<div class=\\\"bar\\\"></div>\";\n  return \"<div class=\\\"bar\\\">\" + CATEGORIES.map((cat) => {\n    const value = categories[cat] || 0;\n    if (!value) return \"\";\n    const width = Math.max(1, pct(value, total));\n    return \"<span title=\\\"\" + escapeHtml(LABELS[cat]) + \"\\\" style=\\\"width:\" + width.toFixed(2) + \"%;background:\" + COLORS[cat] + \"\\\"></span>\";\n  }).join(\"\") + \"</div>\";\n}\n\nfunction renderHtml(sessions, args) {\n  const agg = aggregate(sessions);\n  const totalTokens = sessions.reduce((sum, s) => sum + s.tokens, 0);\n  const tips = recommendations(sessions);\n  const categoryRows = CATEGORIES.map((cat) => {\n    const chars = agg.categories[cat] || 0;\n    if (!chars) return \"\";\n    return \"<tr><td>\" + escapeHtml(LABELS[cat]) + \"</td><td>\" + fmtTokens(estimateTokens(chars)) + \"</td><td>\" + pct(chars, Object.values(agg.categories).reduce((sum, value) => sum + value, 0)).toFixed(0) + \"%</td></tr>\";\n  }).join(\"\");\n  const sessionCards = sessions.map((session) => {\n    const cats = Object.entries(session.categories).sort((a, b) => b[1] - a[1]).map((entry) => \"<tr><td>\" + escapeHtml(LABELS[entry[0]] || entry[0]) + \"</td><td>\" + fmtTokens(estimateTokens(entry[1])) + \"</td><td>\" + pct(entry[1], session.totalChars).toFixed(0) + \"%</td></tr>\").join(\"\");\n    const tools = sortedEntries(session.tools, 6).map((entry) => \"<span class=\\\"badge\\\">\" + escapeHtml(entry[0]) + \" x\" + entry[1] + \"</span>\").join(\"\");\n    const paths = sortedEntries(session.paths, 5).map((entry) => \"<span class=\\\"badge muted\\\">\" + escapeHtml(entry[0]) + \" x\" + entry[1] + \"</span>\").join(\"\");\n    return \"<article class=\\\"card session\\\"><div class=\\\"session-head\\\"><div><div class=\\\"eyebrow\\\">\" + escapeHtml(session.source) + \" - \" + escapeHtml(session.updatedAt || \"unknown time\") + \"</div><h3>\" + escapeHtml(session.title || session.sessionId) + \"</h3><p class=\\\"path\\\">\" + escapeHtml(session.cwd || session.path) + \"</p></div><div class=\\\"token-big\\\">\" + fmtTokens(session.tokens) + \"</div></div>\" + categoryBar(session.categories) + \"<div class=\\\"session-grid\\\"><table><tbody>\" + cats + \"</tbody></table><div><div class=\\\"mini-label\\\">Frequent tools</div><div class=\\\"badges\\\">\" + (tools || \"<span class=\\\"muted-text\\\">none detected</span>\") + \"</div><div class=\\\"mini-label\\\">Repeated paths</div><div class=\\\"badges\\\">\" + (paths || \"<span class=\\\"muted-text\\\">none detected</span>\") + \"</div></div></div></article>\";\n  }).join(\"\");\n  const topTools = sortedEntries(agg.tools, 10).map((entry) => \"<tr><td>\" + escapeHtml(entry[0]) + \"</td><td>\" + entry[1] + \"</td></tr>\").join(\"\");\n  const topPaths = sortedEntries(agg.paths, 10).map((entry) => \"<tr><td>\" + escapeHtml(entry[0]) + \"</td><td>\" + entry[1] + \"</td></tr>\").join(\"\");\n  const sourceCounts = sessions.reduce((counts, s) => (counts[s.source] = (counts[s.source] || 0) + 1, counts), {});\n  return \"<!doctype html><html><head><meta charset=\\\"utf-8\\\"><meta name=\\\"viewport\\\" content=\\\"width=device-width,initial-scale=1\\\"><title>Context X-Ray</title><style>\" +\n    \"body{margin:0;background:#0e1116;color:#f3f5f8;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;line-height:1.45}main{max-width:1180px;margin:0 auto;padding:32px 20px 56px}header{display:flex;justify-content:space-between;gap:24px;align-items:flex-end;margin-bottom:24px}h1{margin:0;font-size:clamp(28px,5vw,52px);letter-spacing:0}h2{margin:0 0 14px;font-size:18px}h3{margin:3px 0 4px;font-size:17px}p{margin:0}.muted,.path,.eyebrow,.muted-text{color:#9aa3ad}.eyebrow{text-transform:uppercase;letter-spacing:.08em;font-size:11px}.summary{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px;margin:18px 0}.card{background:linear-gradient(180deg,#151922,#1c2230);border:1px solid #2a3140;border-radius:8px;padding:16px;box-shadow:0 12px 40px rgba(0,0,0,.22)}.stat strong{display:block;font-size:28px;line-height:1.1}.grid{display:grid;grid-template-columns:minmax(0,1.5fr) minmax(280px,.8fr);gap:16px;align-items:start}.bar{display:flex;overflow:hidden;height:14px;border-radius:999px;background:#252b37;margin:12px 0}.bar span{display:block;min-width:2px}.tips li{margin:0 0 9px}.session{margin-top:14px}.session-head{display:flex;justify-content:space-between;gap:16px}.token-big{font-weight:700;font-size:28px;color:#8ba8ff;white-space:nowrap}.session-grid{display:grid;grid-template-columns:260px minmax(0,1fr);gap:14px;margin-top:12px}table{width:100%;border-collapse:collapse;font-size:13px}td{border-top:1px solid #2a3140;padding:7px 0;vertical-align:top}td:last-child{text-align:right;color:#9aa3ad}.mini-label{margin:7px 0 6px;font-size:11px;text-transform:uppercase;letter-spacing:.08em;color:#9aa3ad}.badges{display:flex;flex-wrap:wrap;gap:6px}.badge{display:inline-flex;border:1px solid #2a3140;border-radius:999px;padding:3px 8px;font-size:12px;background:rgba(255,255,255,.04)}.badge.muted{color:#9aa3ad}footer{color:#9aa3ad;margin-top:24px;font-size:12px}@media(max-width:840px){header,.grid,.session-grid{grid-template-columns:1fr;display:grid}.summary{grid-template-columns:repeat(2,minmax(0,1fr))}}\" +\n    \"</style></head><body><main><header><div><div class=\\\"eyebrow\\\">Local coding context profile</div><h1>Context X-Ray</h1><p class=\\\"muted\\\">Generated \" + escapeHtml(new Date().toLocaleString()) + \" - mode=\" + escapeHtml(args.mode) + \" - source=\" + escapeHtml(args.source) + \" - since=\" + escapeHtml(args.since) + \"</p></div></header><section class=\\\"summary\\\"><div class=\\\"card stat\\\"><span class=\\\"muted\\\">Sessions</span><strong>\" + sessions.length + \"</strong></div><div class=\\\"card stat\\\"><span class=\\\"muted\\\">Observed/estimated tokens</span><strong>\" + fmtTokens(totalTokens) + \"</strong></div><div class=\\\"card stat\\\"><span class=\\\"muted\\\">Codex</span><strong>\" + (sourceCounts.codex || 0) + \"</strong></div><div class=\\\"card stat\\\"><span class=\\\"muted\\\">Claude</span><strong>\" + (sourceCounts.claude || 0) + \"</strong></div></section><section class=\\\"card\\\"><h2>Where The Context Is Going</h2>\" + categoryBar(agg.categories) + \"<table><tbody>\" + categoryRows + \"</tbody></table></section><div class=\\\"grid\\\" style=\\\"margin-top:16px\\\"><section class=\\\"card tips\\\"><h2>Warnings And Optimizations</h2><ol>\" + tips.map((tip) => \"<li>\" + escapeHtml(tip) + \"</li>\").join(\"\") + \"</ol></section><section class=\\\"card\\\"><h2>Hotspots</h2><div class=\\\"mini-label\\\">Top tools</div><table><tbody>\" + (topTools || \"<tr><td>None detected</td><td></td></tr>\") + \"</tbody></table><div class=\\\"mini-label\\\">Top paths</div><table><tbody>\" + (topPaths || \"<tr><td>None detected</td><td></td></tr>\") + \"</tbody></table></section></div><section style=\\\"margin-top:16px\\\"><h2>Sessions</h2>\" + sessionCards + \"</section><footer>Reads local transcript files only. No transcript content is uploaded.</footer></main></body></html>\";\n}\n\nfunction writeJson(sessions, args, file) {\n  const agg = aggregate(sessions);\n  fs.writeFileSync(file, JSON.stringify({\n    generatedAt: new Date().toISOString(),\n    mode: args.mode,\n    source: args.source,\n    since: args.since,\n    totalTokens: sessions.reduce((sum, s) => sum + s.tokens, 0),\n    categories: agg.categories,\n    tools: sortedEntries(agg.tools, 25),\n    paths: sortedEntries(agg.paths, 25),\n    recommendations: recommendations(sessions),\n    sessions,\n  }, null, 2));\n}\n\nfunction openUrl(url) {\n  const cmd = process.platform === \"darwin\" ? \"open\" : process.platform === \"win32\" ? \"cmd\" : \"xdg-open\";\n  const args = process.platform === \"win32\" ? [\"/c\", \"start\", \"\", url] : [url];\n  try {\n    childProcess.spawn(cmd, args, { detached: true, stdio: \"ignore\" }).unref();\n  } catch {}\n}\n\nfunction printSummary(sessions, args, file, url) {\n  const total = sessions.reduce((sum, s) => sum + s.tokens, 0);\n  console.log(\"Context X-Ray: analyzed \" + sessions.length + \" session(s), about \" + fmtTokens(total) + \" observed/estimated tokens.\");\n  if (url) console.log(\"Open: \" + url);\n  else console.log(\"Report: \" + file);\n  console.log(\"\");\n  for (const tip of recommendations(sessions).slice(0, 4)) console.log(\"- \" + tip);\n  const tools = sortedEntries(aggregate(sessions).tools, 5);\n  if (tools.length) console.log(\"- Frequent tools: \" + tools.map((entry) => entry[0] + \" x\" + entry[1]).join(\", \"));\n}\n\nfunction main() {\n  const args = parseArgs(process.argv.slice(2));\n  if (args.help) return help();\n  const sessions = collectSessions(args);\n  mkdirp(OUT_DIR);\n  const suffix = args.format === \"json\" ? \"json\" : \"html\";\n  const file = args.out || path.join(OUT_DIR, \"context-xray-\" + new Date().toISOString().replace(/[:.]/g, \"-\") + \".\" + suffix);\n  mkdirp(path.dirname(file));\n  if (args.format === \"json\") writeJson(sessions, args, file);\n  else fs.writeFileSync(file, renderHtml(sessions, args));\n  const url = args.open && args.format === \"html\" ? pathToFileURL(file).href : \"\";\n  if (url) openUrl(url);\n  printSummary(sessions, args, file, url);\n}\n\nmain();\n`;\n\nexport const CONTEXT_XRAY_SKILL_MD = `---\nname: context-xray\ndescription: >-\n  Visualize local Codex and Claude Code context usage, open an inline/browser\n  report, flag warnings, and suggest prompt/tooling optimizations. Use when the\n  user types /context-xray, asks where context is going, wants recent local\n  coding-agent trends, or wants to improve context efficiency.\nmetadata:\n  visibility: exported\n---\n\n# Context X-Ray\n\nUse the locally installed Context X-Ray command to visualize recent Codex and\nClaude Code context usage. It reads local transcript files only and does not\nupload transcript content.\n\nProject-scoped installs write only project \\`.agents\\` skill and command\nartifacts; user-scoped installs write global Codex/Claude instructions.\n\n## Run\n\nCurrent or most recent local thread:\n\n\\`\\`\\`sh\n~/.agent-native/context-xray/context-xray --open\n\\`\\`\\`\n\nThread picker / recent sessions:\n\n\\`\\`\\`sh\n~/.agent-native/context-xray/context-xray threads --open\n\\`\\`\\`\n\nWeekly trends:\n\n\\`\\`\\`sh\n~/.agent-native/context-xray/context-xray trends --since 7d --open\n\\`\\`\\`\n\nExact session when the host exposes one:\n\n\\`\\`\\`sh\n~/.agent-native/context-xray/context-xray --session-id \"$CLAUDE_CODE_SESSION_ID\" --open\n\\`\\`\\`\n\nAfter running, report the link, the number of sessions analyzed, the largest\ncontext buckets, and 3-5 specific optimizations.\n\\`--open\\` opens the generated local HTML file directly and does not keep a\nbackground report server running.\n\n## Interpret\n\n- Tool output heavy: use narrower commands, smaller file ranges, and summarized\n  logs.\n- Instructions heavy: move stable behavior into skills or AGENTS/CLAUDE files.\n- Assistant prose heavy: ask for shorter status updates during long runs.\n- One huge session: compact or start a follow-up thread with a handoff summary.\n- Repeated path: pin a short file-role summary instead of rereading the file.\n- Repeated tool: batch independent searches or delegate parallel inspection.\n`;\n\nexport const CONTEXT_XRAY_COMMAND_MD = `---\ndescription: Visualize local Codex/Claude context usage and get optimization tips.\nargument-hint: [current|threads|trends|--since 7d]\n---\n\nRun Context X-Ray locally and show the user the generated report link plus the\ntop warnings.\n\nChoose the command from the user's arguments:\n\n- No arguments or \\`current\\`:\n  \\`~/.agent-native/context-xray/context-xray --open\\`\n- \\`threads\\`:\n  \\`~/.agent-native/context-xray/context-xray threads --open\\`\n- \\`trends\\`:\n  \\`~/.agent-native/context-xray/context-xray trends --since 7d --open\\`\n\nIf \\`$ARGUMENTS\\` includes flags such as \\`--since 24h\\`, \\`--last 20\\`, or\n\\`--all-projects\\`, pass them through to the command. If the host exposes\n\\`CLAUDE_CODE_SESSION_ID\\`, prefer:\n\n\\`\\`\\`sh\n~/.agent-native/context-xray/context-xray --session-id \"$CLAUDE_CODE_SESSION_ID\" --open\n\\`\\`\\`\n\n\\`--open\\` opens a local HTML report file directly; there should not be a\nlong-running server process to monitor.\n\nAfter the command finishes, summarize:\n\n- the report link\n- sessions analyzed\n- the largest context bucket\n- the most important warning\n- two or three concrete ways to improve this thread\n`;\n\nfunction codexHome(): string {\n  return process.env.CODEX_HOME?.trim() || path.join(os.homedir(), \".codex\");\n}\n\nfunction writeExecutable(file: string, content: string): void {\n  fs.mkdirSync(path.dirname(file), { recursive: true });\n  fs.writeFileSync(file, content, \"utf-8\");\n  fs.chmodSync(file, 0o755);\n}\n\nfunction writeFile(file: string, content: string, written: string[]): void {\n  fs.mkdirSync(path.dirname(file), { recursive: true });\n  fs.writeFileSync(file, content, \"utf-8\");\n  written.push(file);\n}\n\nfunction installProjectArtifacts(baseDir: string, written: string[]): void {\n  writeFile(\n    path.join(baseDir, \".agents\", \"skills\", \"context-xray\", \"SKILL.md\"),\n    CONTEXT_XRAY_SKILL_MD,\n    written,\n  );\n  writeFile(\n    path.join(baseDir, \".agents\", \"commands\", \"context-xray.md\"),\n    CONTEXT_XRAY_COMMAND_MD,\n    written,\n  );\n}\n\nexport function installLocalContextXray(\n  options: InstallLocalContextXrayOptions,\n): InstallLocalContextXrayResult {\n  const installDir = path.join(os.homedir(), \".agent-native\", \"context-xray\");\n  const scriptPath = path.join(installDir, \"context-xray\");\n  const binPath = path.join(os.homedir(), \".local\", \"bin\", \"context-xray\");\n  const written: string[] = [];\n\n  if (options.dryRun) {\n    return {\n      commands: [\"context-xray --open\"],\n      scriptPath,\n      written,\n    };\n  }\n\n  writeExecutable(scriptPath, CONTEXT_XRAY_EXECUTABLE);\n  written.push(scriptPath);\n  if (process.platform === \"win32\") {\n    const cmdPath = `${binPath}.cmd`;\n    writeExecutable(\n      cmdPath,\n      `@echo off\\r\\nnode ${JSON.stringify(scriptPath)} %*\\r\\n`,\n    );\n    written.push(cmdPath);\n  } else {\n    writeExecutable(\n      binPath,\n      `#!/usr/bin/env sh\\nexec ${JSON.stringify(scriptPath)} \"$@\"\\n`,\n    );\n    written.push(binPath);\n  }\n\n  const clientSet = new Set(options.clients);\n  const wantsCodex = clientSet.has(\"codex\");\n  const wantsClaude =\n    clientSet.has(\"claude-code\") || clientSet.has(\"claude-code-cli\");\n\n  if (options.scope === \"project\" && options.baseDir) {\n    installProjectArtifacts(options.baseDir, written);\n  } else if (wantsCodex) {\n    writeFile(\n      path.join(codexHome(), \"skills\", \"context-xray\", \"SKILL.md\"),\n      CONTEXT_XRAY_SKILL_MD,\n      written,\n    );\n    writeFile(\n      path.join(codexHome(), \"commands\", \"context-xray.md\"),\n      CONTEXT_XRAY_COMMAND_MD,\n      written,\n    );\n  }\n\n  if (options.scope !== \"project\" && wantsClaude) {\n    writeFile(\n      path.join(os.homedir(), \".claude\", \"skills\", \"context-xray\", \"SKILL.md\"),\n      CONTEXT_XRAY_SKILL_MD,\n      written,\n    );\n    writeFile(\n      path.join(os.homedir(), \".claude\", \"commands\", \"context-xray.md\"),\n      CONTEXT_XRAY_COMMAND_MD,\n      written,\n    );\n  }\n\n  return {\n    commands: [\"context-xray --open\"],\n    scriptPath,\n    written,\n  };\n}\n"]}

package/dist/cli/skills.d.ts

@@ -34,6 +34,9 @@ export interface SkillsAddResult {
     mcpClients: ClientId[];
     dryRun: boolean;
     commands: string[];
+    local?: boolean;
+    scriptPath?: string;
+    written?: string[];
 }
 interface RunCommandOptions {
     stdio?: "inherit" | "stderr" | "silent";

package/dist/cli/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAocjE,KAAK,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAWD,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACzC;AAED,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,aAAa,CAAC,EAAE,CACd,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;IAChC,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,CACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,iBAAiB,KACxB,OAAO,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,UAAU,yBAAyB;IACjC,cAAc,EAAE,QAAQ,EAAE,CAAC;IAC3B,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,UAAU,yBAAyB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAsID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAgEhE;AAkND,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkG1B;AAeD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA0Ff"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4gBjE,KAAK,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,GAAG,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAWD,UAAU,iBAAiB;IACzB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACzC;AAED,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,aAAa,CAAC,EAAE,CACd,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;IAChC,YAAY,CAAC,EAAE,CACb,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,CACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,iBAAiB,KACxB,OAAO,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,UAAU,yBAAyB;IACjC,cAAc,EAAE,QAAQ,EAAE,CAAC;IAC3B,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,UAAU,yBAAyB;IACjC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AA4ID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAgEhE;AAkND,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAiJ1B;AAgBD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAyGf"}

package/dist/cli/skills.js

@@ -9,18 +9,20 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { buildAppSkillPack, ensureAppSkill, loadAppSkillManifest, normalizeAppSkillManifest, } from "./app-skill.js";
 import { readConnectClientPreferences, resolveClients, writeConnectClientPreferences, } from "./connect.js";
+import { CONTEXT_XRAY_SKILL_MD, installLocalContextXray, } from "./context-xray-local.js";
 import { CLIENTS } from "./mcp-config-writers.js";
 const HELP = `agent-native skills
 
 Usage:
   agent-native skills list
-  agent-native skills add assets|design-exploration|contracts [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--yes] [--dry-run] [--json]
+  agent-native skills add assets|design-exploration|visual-plans|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--yes] [--dry-run] [--json]
   agent-native skills add <manifest-or-app-dir> [--client ...] [--yes]
 
 Examples:
   agent-native skills add assets
   agent-native skills add design-exploration
-  agent-native skills add contracts
+  agent-native skills add visual-plans
+  agent-native skills add context-xray --client all
   agent-native skills add assets --client claude-code
   agent-native skills add assets --mcp-url https://my-app.ngrok-free.dev
   agent-native skills add ./dist/assets-skill --client codex
@@ -183,33 +185,37 @@ iteration, or a human-in-the-loop choice among design directions.
 - If you inspect local MCP config, redact \`Authorization\`, \`http_headers\`,
   and token values. Never paste bearer tokens into chat or logs.
 `;
-const CONTRACTS_SKILL_MD = `---
-name: contracts
+const VISUAL_PLANS_SKILL_MD = `---
+name: visual-plans
 description: >-
-  Use Contracts for coding-agent work that needs assumption review, mid-flight
-  feedback, acceptance criteria, evidence capture, and proof-before-done
-  through the hosted Contracts MCP app.
+  Use Visual Plans for coding-agent work that needs an interactive HTML plan,
+  diagrams, wireframes, prototype options, annotations, implementation tasks,
+  feedback, and proof gates through the hosted Visual Plans MCP app.
 metadata:
   visibility: exported
 ---
 
-# Contracts
+# Visual Plans
 
-Use Contracts as the trust layer for non-trivial coding work. It records what
-the agent is assuming, lets a human correct those assumptions before they become
-code, and keeps acceptance criteria separate from verified evidence.
+Use Visual Plans as HTML plan mode for coding work. The point is not to create a
+prettier Markdown plan. The point is to give the user something visual to react
+to before the agent edits code: diagrams, wireframes, option cards, clickable
+prototype sketches, assumptions, tasks, annotations, and proof gates.
+
+Text is the fallback layer. Default to visual artifacts.
 
 ## When To Use
 
-Create or update a contract when:
+Create or update a visual plan when:
 
-- the user asks for Contracts, specs, proof, review, acceptance criteria, or a
-  structured plan;
-- work is multi-file, ambiguous, long-running, or risky;
+- the user asks for a plan, visual plan, HTML plan, plannotate-style review,
+  diagrams, wireframes, mockups, prototype options, comments, or annotations;
+- work is multi-file, ambiguous, long-running, risky, or UI-heavy;
+- the user needs to react quickly to direction rather than read prose;
 - the task touches auth, billing, migrations, public APIs, tests, production
   config, data, security, permissions, or deploy behavior;
 - you would otherwise proceed on a material assumption;
-- you are about to claim the work is complete.
+- you are about to claim the work is complete and need proof gates checked.
 
 Do not log every trivial inference. An assumption is material when changing it
 would affect user-visible behavior, data model, permissions, billing, public API
@@ -218,52 +224,60 @@ deployment/configuration, file scope, or the definition of done.
 
 ## Core Workflow
 
-1. Call \`create-contract\` with the goal, source, repo path, and initial
-   assumptions/criteria before risky implementation.
-2. Surface the returned Contracts UI link or inline MCP App. In CLI hosts, tell
-   the user to open the link and review the queue.
-3. Call \`get-feedback\` before risky edits, after review, after any long pause,
+1. Call \`create-visual-plan\` with the goal, source, repo path, and initial
+   plan nodes before implementation.
+2. Surface the returned Visual Plans link or inline MCP App. In CLI hosts, tell
+   the user to open the link and review the visual plan.
+3. Prefer diagrams, wireframes, UI mockups, option cards, and small interactive
+   prototypes over paragraphs.
+4. Call \`get-plan-feedback\` before editing, after review, after any long pause,
    and before the final response.
-4. If the user accepts, rejects, corrects, or requests evidence, consume the
-   structured feedback and change your plan accordingly.
-5. If new facts require a change after approval, create an \`amendment\` or
-   \`deviation\` item with \`upsert-contract-items\` instead of drifting silently.
-6. Attach command/test/log/diff/screenshot evidence with \`record-evidence\`.
-7. Do not treat your own claim as proof. Agent attestation is low trust.
-   Criteria are done only when verified by human, CI, deterministic checks, or
-   an independent verifier.
-8. Export a JSON/Markdown receipt with \`export-contract\` when the user wants a
-   shareable summary.
+5. If the user comments, accepts, rejects, corrects, or requests proof, consume
+   the structured feedback and update the implementation plan accordingly.
+6. If new facts require a change after approval, create an amendment or
+   deviation with \`update-visual-plan\` instead of drifting silently.
+7. Attach command/test/log/diff/screenshot/design artifacts with
+   \`record-plan-evidence\`. Agent claims are not proof.
+8. Export an HTML/JSON/Markdown receipt with \`export-visual-plan\` when the
+   user wants a shareable summary.
+
+## Visual Defaults
+
+- UI work gets wireframes or prototype options before coding.
+- Backend/refactor work gets architecture and data-flow diagrams.
+- Complex tradeoffs get two or three option cards with consequences.
+- Assumptions are shown as reviewable visual callouts, not hidden prose.
+- Proof gates stay compact: what must pass, current evidence, and missing proof.
+- Long prose is collapsed behind the visual plan.
 
 ## Tool Guidance
 
-- \`create-contract\`: start one contract per agent task/run.
-- \`upsert-contract-items\`: bulk add/update assumptions, decisions, criteria,
-  risks, deviations, open questions, and amendments.
-- \`get-contract\` and \`get-review-queue\`: read current structured state.
-- \`get-feedback\`: read unconsumed human feedback. Use it frequently.
-- \`record-progress\`: update phase/status and mark feedback consumed only after
-  you incorporated it.
-- \`record-evidence\`: attach artifacts and provenance. Use high trust for
+- \`create-visual-plan\`: start one visual plan per agent task/run.
+- \`update-visual-plan\`: bulk add/update plan nodes, options, assumptions,
+  decisions, tasks, risks, deviations, annotations, and proof gates.
+- \`get-visual-plan\` and \`get-plan-review-queue\`: read current plan state.
+- \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently.
+- \`record-plan-progress\`: update phase/status and mark feedback consumed only
+  after you incorporated it.
+- \`record-plan-evidence\`: attach artifacts and provenance. Use high trust for
   captured commands/tests/CI, human_confirmed for explicit human confirmation,
   and low trust for agent-only statements.
-- \`analyze-plan\`: import pasted plan text and let Contracts create possible
-  assumptions/criteria. Treat detections as possible, not authoritative.
+- \`analyze-visual-plan\`: import pasted Markdown/text and create possible
+  visual plan nodes. Treat detections as possible, not authoritative.
 
 ## Guardrails
 
+- Keep it simple. Do not build a ten-tab dashboard unless the user asks.
 - Before high-risk actions, create a blocking review item or ask the user
   directly.
-- Never modify tests merely to make implementation pass unless the contract
+- Never modify tests merely to make implementation pass unless the visual plan
   explicitly approves test expectation changes.
 - If proof is missing, say so. Do not call the task complete just because code
   was changed.
-- If evidence contains secrets or tokens, rely on Contracts redaction and avoid
-  pasting raw output into chat.
 - Do not hand-roll MCP HTTP requests with curl. Use host-exposed tools after
   restart/reload, or use the returned browser/deep-link fallback.
 - Hosted default: connect
-  \`https://contracts.agent-native.com/_agent-native/mcp\`. Do not put shared
+  \`https://plans.agent-native.com/_agent-native/mcp\`. Do not put shared
   secrets in skill files.
 `;
 const BUILT_IN_APP_SKILLS = {
@@ -353,34 +367,34 @@ const BUILT_IN_APP_SKILLS = {
         }),
         skillMarkdown: DESIGN_EXPLORATION_SKILL_MD,
     },
-    contracts: {
-        skillName: "contracts",
+    "visual-plans": {
+        skillName: "visual-plans",
         manifest: normalizeAppSkillManifest({
             schemaVersion: 1,
-            id: "contracts",
-            displayName: "Contracts",
-            description: "Review coding-agent assumptions, feedback, acceptance criteria, and proof before work is called done.",
+            id: "visual-plans",
+            displayName: "Visual Plans",
+            description: "Review coding-agent plans as interactive HTML with diagrams, wireframes, annotations, and proof gates.",
             hosted: {
-                url: "https://contracts.agent-native.com",
-                mcpUrl: "https://contracts.agent-native.com/_agent-native/mcp",
+                url: "https://plans.agent-native.com",
+                mcpUrl: "https://plans.agent-native.com/_agent-native/mcp",
             },
-            mcp: { serverName: "agent-native-contracts" },
+            mcp: { serverName: "agent-native-visual-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Authenticate with the Contracts MCP connector in the host app. No shared secrets are stored in skill files.",
+                setup: "Authenticate with the Visual Plans MCP connector in the host app. No shared secrets are stored in skill files.",
             },
             surfaces: [
                 {
-                    id: "review-inbox",
-                    action: "create-contract",
-                    path: "/contracts",
+                    id: "visual-plan",
+                    action: "create-visual-plan",
+                    path: "/plans",
                 },
             ],
             skills: [
                 {
-                    path: "skills/contracts",
+                    path: "skills/visual-plans",
                     visibility: "exported",
-                    exportAs: "contracts",
+                    exportAs: "visual-plans",
                 },
             ],
             hostAdapters: [
@@ -393,7 +407,38 @@ const BUILT_IN_APP_SKILLS = {
                 "generic-mcp",
             ],
         }),
-        skillMarkdown: CONTRACTS_SKILL_MD,
+        skillMarkdown: VISUAL_PLANS_SKILL_MD,
+    },
+    "context-xray": {
+        skillName: "context-xray",
+        localOnly: true,
+        manifest: normalizeAppSkillManifest({
+            schemaVersion: 1,
+            id: "context-xray",
+            displayName: "Context X-Ray",
+            description: "Visualize local Codex and Claude Code context usage with warnings and optimization tips.",
+            hosted: {
+                url: "https://context-xray.agent-native.com",
+                mcpUrl: "https://context-xray.agent-native.com/_agent-native/mcp",
+            },
+            mcp: { serverName: "agent-native-context-xray" },
+            auth: { mode: "none" },
+            surfaces: [
+                {
+                    id: "context-xray-report",
+                    path: "/",
+                },
+            ],
+            skills: [
+                {
+                    path: "skills/context-xray",
+                    visibility: "exported",
+                    exportAs: "context-xray",
+                },
+            ],
+            hostAdapters: ["plain-skill", "claude-skill"],
+        }),
+        skillMarkdown: CONTEXT_XRAY_SKILL_MD,
     },
 };
 const BUILT_IN_APP_SKILL_ALIASES = {
@@ -412,12 +457,27 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "ux-exploration": "design",
     "agent-native-design": "design",
     "agent-native-design-exploration": "design",
-    contracts: "contracts",
-    contract: "contracts",
-    proof: "contracts",
-    "proof-check": "contracts",
-    "assumption-review": "contracts",
-    "agent-native-contracts": "contracts",
+    "visual-plans": "visual-plans",
+    "visual-plan": "visual-plans",
+    plans: "visual-plans",
+    plan: "visual-plans",
+    "html-plan": "visual-plans",
+    "plan-mode": "visual-plans",
+    plannotate: "visual-plans",
+    plannotator: "visual-plans",
+    contracts: "visual-plans",
+    contract: "visual-plans",
+    proof: "visual-plans",
+    "proof-check": "visual-plans",
+    "assumption-review": "visual-plans",
+    "agent-native-contracts": "visual-plans",
+    "agent-native-visual-plans": "visual-plans",
+    "context-xray": "context-xray",
+    "local-context-xray": "context-xray",
+    xray: "context-xray",
+    "context-window": "context-xray",
+    "context-usage": "context-xray",
+    "agent-native-context-xray": "context-xray",
 };
 const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     assets: ["images", "image-generation", "agent-native-images"],
@@ -426,7 +486,14 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
         "ux-exploration",
         "agent-native-design-exploration",
     ],
-    contracts: ["contract", "proof-check", "assumption-review"],
+    "visual-plans": [
+        "plans",
+        "html-plan",
+        "plannotate",
+        "contracts",
+        "proof-check",
+    ],
+    "context-xray": ["xray", "context-window", "context-usage"],
 };
 const CLIENT_LABELS = {
     "claude-code": "Claude Code",
@@ -449,6 +516,9 @@ function normalizeKnownSkillTarget(value) {
 function isKnownSkill(value) {
     return Boolean(normalizeKnownSkillTarget(value));
 }
+function isLocalOnlyBuiltInSkill(entry) {
+    return Boolean(entry && "localOnly" in entry && entry.localOnly);
+}
 function normalizeClientIds(values) {
     if (!Array.isArray(values))
         return [];
@@ -823,6 +893,49 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     if (!knownTarget && !fs.existsSync(path.resolve(target))) {
         throw new Error(`Unknown skill or manifest path: ${target}. Run "agent-native skills list".`);
     }
+    const knownBuiltIn = knownTarget ? BUILT_IN_APP_SKILLS[knownTarget] : null;
+    if (isLocalOnlyBuiltInSkill(knownBuiltIn)) {
+        if (parsed.mcpUrl) {
+            throw new Error("Context X-Ray is installed locally and does not use --mcp-url yet.");
+        }
+        if (!parsed.instructions && parsed.mcp) {
+            throw new Error("Context X-Ray does not need MCP config yet. Run without --mcp-only.");
+        }
+        const clients = parsed.clients ?? resolveClients(parsed.client);
+        const skillsAgents = skillsAgentsForClients(clients);
+        if (parsed.dryRun) {
+            return {
+                id: knownBuiltIn.manifest.id,
+                displayName: knownBuiltIn.manifest.displayName,
+                skillNames: [knownBuiltIn.skillName],
+                skillsAgents,
+                mcpUrl: "",
+                mcpClients: [],
+                dryRun: true,
+                local: true,
+                commands: [dryRunInstallCommand(parsed, target)],
+            };
+        }
+        const localInstall = installLocalContextXray({
+            baseDir: options.baseDir ?? process.cwd(),
+            clients,
+            scope: parsed.scope,
+        });
+        return {
+            id: knownBuiltIn.manifest.id,
+            displayName: knownBuiltIn.manifest.displayName,
+            instructionSource: localInstall.scriptPath,
+            skillNames: [knownBuiltIn.skillName],
+            skillsAgents,
+            mcpUrl: "",
+            mcpClients: [],
+            dryRun: false,
+            local: true,
+            scriptPath: localInstall.scriptPath,
+            written: localInstall.written,
+            commands: localInstall.commands,
+        };
+    }
     let installTarget = loadSkillTarget(target);
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
@@ -916,7 +1029,8 @@ function listSkills() {
         aliases: BUILT_IN_APP_SKILL_DISPLAY_ALIASES[entry.manifest.id] ?? [],
         name: entry.manifest.displayName,
         description: entry.manifest.description,
-        mcpUrl: entry.manifest.hosted.mcpUrl,
+        mcpUrl: isLocalOnlyBuiltInSkill(entry) ? "" : entry.manifest.hosted.mcpUrl,
+        local: isLocalOnlyBuiltInSkill(entry),
     }));
 }
 export async function runSkills(argv, options = {}) {
@@ -939,7 +1053,8 @@ export async function runSkills(argv, options = {}) {
             const aliases = skill.aliases.length
                 ? ` Aliases: ${skill.aliases.join(", ")}.`
                 : "";
-            process.stdout.write(`${skill.id.padEnd(12)} ${description}${aliases} (${skill.mcpUrl})\n`);
+            const target = skill.local ? "local command" : skill.mcpUrl;
+            process.stdout.write(`${skill.id.padEnd(12)} ${description}${aliases} (${target})\n`);
         }
         return;
     }
@@ -976,15 +1091,27 @@ export async function runSkills(argv, options = {}) {
     const mcpClients = [
         ...new Set(results.flatMap((result) => result.mcpClients)),
     ];
-    const mcpUrls = [...new Set(results.map((result) => result.mcpUrl))];
+    const mcpUrls = [
+        ...new Set(results.map((result) => result.mcpUrl).filter(Boolean)),
+    ];
+    const localCommands = [
+        ...new Set(results
+            .filter((result) => result.local)
+            .flatMap((result) => result.commands)),
+    ];
     process.stdout.write([
         `Installed ${installedNames} skill${results.length === 1 ? "" : "s"}.`,
         skillsAgents.length
             ? `Skill instructions: ${skillsAgents.join(", ")}.`
             : "Skill instructions: skipped.",
-        `MCP config: ${mcpClients.join(", ")}.`,
-        `MCP URL${mcpUrls.length === 1 ? "" : "s"}: ${mcpUrls.join(", ")}.`,
-        "Restart or reload selected agent clients if the tools are not visible yet.",
+        mcpClients.length
+            ? `MCP config: ${mcpClients.join(", ")}.`
+            : "MCP config: not required.",
+        mcpUrls.length
+            ? `MCP URL${mcpUrls.length === 1 ? "" : "s"}: ${mcpUrls.join(", ")}.`
+            : "",
+        localCommands.length ? `Local command: ${localCommands.join(", ")}.` : "",
+        "Restart or reload selected agent clients if the skill is not visible yet.",
         parsed.clientExplicit
             ? ""
             : `To add another client later, rerun with --client <client> (for example: --client claude-code).`,