@ngockhoale/ukit 2.2.7 → 2.2.8

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.8 - 2026-08-28
+
+UKit already picked the right files to open, but the step *after* that — actually entering the
+file — was unoptimised: the agent read the whole thing to find the one function it needed. This
+release adds a signature outline so it can jump straight to a line instead.
+
+The outline is a map for **locating** code, not a substitute for reading it. Any code that is
+about to be changed must still be read; the saving comes from narrower reads, not skipped ones.
+That rule is stated in the shipped `CLAUDE.md` / `AGENTS.md` guidance next to the feature itself.
+
+### Added
+
+- **Indexed symbols now carry `line` and `signature`.** `query-index` and `resolve-context` print
+  an `outline:` block (`line: signature`) for the top suspect files, so an agent can go straight
+  to `Read(file, offset=<line>)`. On this repo, locating the top-3 suspects for a representative
+  query costs 2,082 bytes / 25 lines instead of 131,702 bytes / 4,064 lines of whole-file reads.
+  On by default; `--no-outline` turns it off. Capped at the top 3 files and 12 symbols each.
+- **`getFileOutline()`** in the index core, returning line-sorted, name-deduped rows. Missing
+  file, missing artifact, or a stale schema all resolve to `[]`, so callers can render
+  unconditionally.
+- **First behavioural parity test for the hand-maintained index mirror**
+  (`tests/index/indexCoreParity.test.js`). `templates/.claude/ukit/index/lib/index-core.mjs`
+  duplicates `src/index/*` by hand and was flagged in `MIRROR_PAIRS` but never actually compared;
+  drift could only be caught by reading both files. It is now asserted.
+- **Both harnesses covered.** omp runs the same Node helpers and reads `AGENTS.md`, so the
+  guidance ships identically in `templates/CLAUDE.md` and `templates/AGENTS.md` (byte-identical
+  section bodies, enforced by `tests/consistency/contextDocsParity.test.js`). No separate omp
+  code path was needed.
+
+### Fixed
+
+- **`.vue` line numbers would have been silently wrong.** `extractScriptContent` joined the
+  `<script>` blocks together, so a symbol in the second block reported a line number offset by the
+  whole `<template>` above it. Script regions are now masked in place, preserving byte offsets, so
+  reported lines match the file on disk.
+
+### Changed
+
+- `INDEX_SCHEMA_VERSION` 6 → 7. Existing `.cache/index/` artifacts are invalidated and rebuilt
+  automatically on first use; no migration step and no user action.
+
 ## 2.2.7 - 2026-08-28
 
 Follow-up to 2.2.6: that release only made the wrong-runtime failure message *explain* the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.7",
+  "version": "2.2.8",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/bench/outline-savings.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * outline-savings.mjs — Signature Outline Layer (S8 measurement).
+ *
+ * Reports actual whole-file vs outline byte/line counts for this repo's top-3 suspects on a
+ * representative query, so the CHANGELOG can quote a measured number instead of a guess.
+ *
+ * Usage:
+ *   node scripts/bench/outline-savings.mjs ["<query>"] [--root <dir>] [--limit 3]
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { buildCodeIndex } from '../../src/index/buildIndex.js';
+import { queryCodeIndex, getFileOutline } from '../../src/index/queryIndex.js';
+
+const DEFAULT_QUERY = 'resolveContext';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = readFlagValue(args, '--root') ?? process.cwd();
+  const limit = Number.parseInt(readFlagValue(args, '--limit') ?? '3', 10);
+  const query = collectPositionalArgs(args, ['--root', '--limit']) || DEFAULT_QUERY;
+
+  await buildCodeIndex({ rootDir });
+  const results = await queryCodeIndex({ rootDir, query, limit });
+
+  if (results.length === 0) {
+    console.log(`[bench:outline-savings] no matches for query "${query}"`);
+    return;
+  }
+
+  let wholeFileBytes = 0;
+  let wholeFileLines = 0;
+  let outlineBytes = 0;
+  let outlineLines = 0;
+
+  for (const item of results) {
+    const absolutePath = path.join(rootDir, item.filePath);
+    const content = await fs.readFile(absolutePath, 'utf8');
+    wholeFileBytes += Buffer.byteLength(content, 'utf8');
+    wholeFileLines += content.split('\n').length;
+
+    const outline = await getFileOutline({ rootDir, filePath: item.filePath, limit: Infinity });
+    const rendered = renderOutline(outline);
+    outlineBytes += Buffer.byteLength(rendered, 'utf8');
+    outlineLines += rendered.length === 0 ? 0 : rendered.split('\n').length;
+  }
+
+  console.log(`[bench:outline-savings] query: "${query}", top-${results.length} suspects: ${results.map((r) => r.filePath).join(', ')}`);
+  console.log(`whole-file read of top-${results.length} suspects : ${wholeFileBytes} bytes / ${wholeFileLines} lines`);
+  console.log(`outline of top-${results.length} suspects         : ${outlineBytes} bytes / ${outlineLines} lines`);
+}
+
+function renderOutline(outline) {
+  if (outline.length === 0) {
+    return '';
+  }
+  const labels = outline.map((item) => String(item.line));
+  const labelWidth = Math.max(...labels.map((label) => label.length)) + 1;
+  const lines = ['   outline:'];
+  for (const item of outline) {
+    lines.push(`   ${String(item.line).padStart(labelWidth)}: ${item.signature ?? item.name}`);
+  }
+  return lines.join('\n');
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}
+
+function collectPositionalArgs(argv, flagsWithValues = []) {
+  return argv
+    .filter((arg, index) => !isFlagOrValue(argv, index, flagsWithValues))
+    .join(' ')
+    .trim();
+}
+
+function isFlagOrValue(argv, index, flagsWithValues = []) {
+  const arg = argv[index];
+  if (!arg.startsWith('--')) {
+    const prev = argv[index - 1];
+    return Boolean(prev && flagsWithValues.includes(prev));
+  }
+  return true;
+}
+
+await main();

package/src/cli/commands/indexArgs.js

@@ -1,8 +1,12 @@
-const QUERY_FLAG_DEFINITIONS = new Map([['--limit', { requiresValue: true }]]);
+const QUERY_FLAG_DEFINITIONS = new Map([
+  ['--limit', { requiresValue: true }],
+  ['--no-outline', { requiresValue: false }],
+]);
 const TRIAGE_FLAG_DEFINITIONS = new Map();
 const CONTEXT_FLAG_DEFINITIONS = new Map([
   ['--target', { requiresValue: true }],
   ['--type', { requiresValue: true }],
+  ['--no-outline', { requiresValue: false }],
 ]);
 const VERIFY_FLAG_DEFINITIONS = new Map([
   ['--target', { requiresValue: true }],

package/src/cli/commands/indexTools.js

@@ -7,7 +7,7 @@ import {
 import { resolveContext } from '../../index/resolveContext.js';
 import { deriveVerificationPlan } from '../../index/verificationPlan.js';
 import { deriveTaskRoute } from '../../index/taskRouting.js';
-import { queryCodeIndex } from '../../index/queryIndex.js';
+import { queryCodeIndex, getFileOutline } from '../../index/queryIndex.js';
 import { triageBug } from '../../bug/triageBug.js';
 import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
 import {
@@ -25,6 +25,8 @@ const CONTEXT_REASON_LIMIT = 2;
 const VERIFY_COMMAND_DISPLAY_LIMIT = 2;
 const VERIFY_REASON_DISPLAY_LIMIT = 2;
 const VERIFY_NOTE_DISPLAY_LIMIT = 1;
+const OUTLINE_TOP_FILES_LIMIT = 3;
+const OUTLINE_SYMBOLS_LIMIT = 12;
 
 export async function runIndexTools({ projectRoot, argv = [] }) {
   const [subcommandRaw, ...rest] = argv;
@@ -68,6 +70,7 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
       return;
     }
 
+    const showOutline = !flags.get('--no-outline');
     console.log(`[UKit] Index query top ${results.length} for: ${query}`);
     for (const [idx, item] of results.entries()) {
       console.log(`${idx + 1}. ${item.filePath} (score=${item.score})`);
@@ -77,6 +80,9 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
       if ((item.reasons ?? []).length > 0) {
         console.log(`   reasons: ${item.reasons.join(', ')}`);
       }
+      if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
+        await printOutlineForFile(projectRoot, item.filePath);
+      }
     }
     return;
   }
@@ -118,10 +124,16 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
       taskType,
     });
 
+    const showOutline = !flags.get('--no-outline');
     console.log('[UKit] Suggested context:');
     console.log(`taskType: ${result.taskType}`);
     console.log(`budget: ${result.contextBudget.minFiles}-${result.contextBudget.maxFiles} files`);
     printContextGroup('primaryTargets', result.primaryTargets, result.explanations?.primaryTargets);
+    if (showOutline) {
+      for (const filePath of (result.primaryTargets ?? []).slice(0, OUTLINE_TOP_FILES_LIMIT)) {
+        await printOutlineForFile(projectRoot, filePath);
+      }
+    }
     printContextGroup('sharedAbstractions', result.sharedAbstractions, result.explanations?.sharedAbstractions);
     printContextGroup('analogFiles', result.analogFiles, result.explanations?.analogFiles);
     printContextGroup('relatedTests', result.relatedTests, result.explanations?.relatedTests);
@@ -286,6 +298,29 @@ async function refreshIndexIfStale(rootDir) {
   return true;
 }
 
+async function printOutlineForFile(rootDir, filePath) {
+  const outline = await getFileOutline({ rootDir, filePath, limit: Infinity });
+  if (outline.length === 0) {
+    return;
+  }
+
+  const shown = outline.slice(0, OUTLINE_SYMBOLS_LIMIT);
+  const remaining = outline.length - shown.length;
+  const labels = shown.map((item) => String(item.line));
+  if (remaining > 0) {
+    labels.push(`+${remaining}`);
+  }
+  const labelWidth = Math.max(...labels.map((label) => label.length)) + 1;
+
+  console.log('   outline:');
+  for (const item of shown) {
+    console.log(`   ${String(item.line).padStart(labelWidth)}: ${item.signature ?? item.name}`);
+  }
+  if (remaining > 0) {
+    console.log(`   ${`+${remaining}`.padStart(labelWidth)} more symbols`);
+  }
+}
+
 function printContextGroup(label, filePaths = [], explanations = []) {
   console.log(`${label}: ${formatCompactDisplayList(filePaths)}`);
 

package/src/index/buildIndex.js

@@ -607,36 +607,117 @@ function findScriptClose(content, startIndex) {
   return -1;
 }
 
-function extractScriptContent(filePath, content) {
+export function extractScriptContent(filePath, content) {
   if (!filePath.endsWith('.vue')) {
     return content;
   }
 
-  const scripts = [];
+  // Mask instead of extract: the returned string is the same length as `content`,
+  // with every character outside a <script> body replaced by a space (newlines kept).
+  // That keeps offsets mapped 1:1 to the original file, so line numbers computed
+  // against this string are correct for the file on disk. Extracting and `join('\n')`ing
+  // the bodies (the old approach) destroys that positional relationship.
+  const masked = content.replace(/[^\n]/g, ' ').split('');
+  let foundAny = false;
   const startTagPattern = /<script[^>]*>/gi;
   for (const match of content.matchAll(startTagPattern)) {
     const bodyStart = match.index + match[0].length;
     const bodyEnd = findScriptClose(content, bodyStart);
     if (bodyEnd !== -1) {
-      scripts.push(content.slice(bodyStart, bodyEnd));
+      foundAny = true;
+      for (let i = bodyStart; i < bodyEnd; i += 1) {
+        masked[i] = content[i];
+      }
     }
   }
-  if (scripts.length === 0) return '';
-  return scripts.join('\n');
+  if (!foundAny) return '';
+  return masked.join('');
 }
 
 
-function extractSymbols(filePath, content) {
+// Precompute the start offset of every line once per file, so `line` for a match
+// can be found with a binary search instead of `content.slice(0, i).split('\n').length`
+// (which is O(n) per symbol, O(n^2) across a large file).
+function computeLineStarts(content) {
+  const starts = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === '\n') {
+      starts.push(index + 1);
+    }
+  }
+  return starts;
+}
+
+function lineNumberForIndex(lineStarts, index) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (lineStarts[mid] <= index) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return low + 1;
+}
+
+// Display string only, not a parse: scan forward from the start of the matched line to the
+// `)` that closes the parameter list, or to end-of-line when the line opens no paren. Depth
+// is tracked rather than stopping at the first `)`, otherwise a default-valued parameter
+// truncates mid-expression (`function f({ root = process.cwd() } = {})` would cut at the
+// `)` of `process.cwd()`). The scan is capped at 400 chars so a malformed file cannot walk
+// the whole buffer.
+function computeSignature(content, lineStartIndex) {
+  const boundedEnd = Math.min(content.length, lineStartIndex + 400);
+  let sliceEnd = boundedEnd;
+  let depth = 0;
+  let sawOpenParen = false;
+  for (let index = lineStartIndex; index < boundedEnd; index += 1) {
+    const char = content[index];
+    if (char === '(') {
+      depth += 1;
+      sawOpenParen = true;
+    } else if (char === ')') {
+      depth -= 1;
+      if (sawOpenParen && depth <= 0) {
+        sliceEnd = index + 1;
+        break;
+      }
+    } else if (char === '\n' && !sawOpenParen) {
+      sliceEnd = index;
+      break;
+    }
+  }
+
+  // Keep a trailing `=>` so an arrow function stays distinguishable from an ordinary
+  // parenthesised expression. getFileOutline relies on that to filter outline noise.
+  const arrowMatch = /^\s*=>/.exec(content.slice(sliceEnd, Math.min(content.length, sliceEnd + 8)));
+  if (arrowMatch) {
+    sliceEnd += arrowMatch[0].length;
+  }
+
+  const collapsed = content.slice(lineStartIndex, sliceEnd).replace(/\s+/g, ' ').trim();
+  if (collapsed.length <= 200) {
+    return collapsed;
+  }
+  return `${collapsed.slice(0, 199)}…`;
+}
+
+export function extractSymbols(filePath, content) {
   const symbols = [];
-  const addSymbol = (name, type) => {
+  const lineStarts = computeLineStarts(content);
+  const addSymbol = (name, type, matchIndex = null) => {
     if (!name) {
       return;
     }
-    symbols.push({
-      name,
-      type,
-      filePath,
-    });
+    if (matchIndex === null) {
+      symbols.push({ name, type, filePath, line: null, signature: null });
+      return;
+    }
+    const line = lineNumberForIndex(lineStarts, matchIndex);
+    const signature = computeSignature(content, lineStarts[line - 1]);
+    symbols.push({ name, type, filePath, line, signature });
   };
   const addMatches = (regex, type, groupIndex = 1) => {
     for (const match of content.matchAll(regex)) {
@@ -644,7 +725,7 @@ function extractSymbols(filePath, content) {
       if (!symbolName) {
         continue;
       }
-      addSymbol(symbolName, type);
+      addSymbol(symbolName, type, match.index);
     }
   };
 
@@ -671,7 +752,7 @@ function extractSymbols(filePath, content) {
       if (!aliasMatch) {
         continue;
       }
-      addSymbol(aliasMatch[2] ?? aliasMatch[1], 'named-export');
+      addSymbol(aliasMatch[2] ?? aliasMatch[1], 'named-export', match.index);
     }
   }
 

package/src/index/paths.js

@@ -13,7 +13,7 @@ export const INDEX_ARTIFACTS = {
   analogs: 'analogs.json',
 };
 
-export const INDEX_SCHEMA_VERSION = 6;
+export const INDEX_SCHEMA_VERSION = 7;
 
 export function getIndexDir(rootDir) {
   return path.join(rootDir, '.cache', 'index');

package/src/index/queryIndex.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, isLikelyTestFilePath } from './paths.js';
+import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath } from './paths.js';
 import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
 import { buildSearchDescriptor } from './languageTools.js';
 
@@ -130,6 +130,62 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
   return queryPromise;
 }
 
+// The `callable` symbol regex matches any `const x = (`, so it also captures plain
+// parenthesised expressions such as `const rows = (items ?? [])`. Harmless for fuzzy
+// ranking, misleading in an outline that is read as a map of the file's API. Those rows
+// stay in symbols.json and are dropped here instead.
+function isFunctionLikeSignature(signature) {
+  const normalized = String(signature ?? '');
+  // computeSignature only appends `=>` directly after a balanced parameter list, so a
+  // trailing arrow is a reliable marker and body text that merely contains one is not.
+  if (normalized.endsWith('=>')) {
+    return true;
+  }
+  // `function`/`class` must belong to the declaration head, not to body text the bounded
+  // scan happened to include.
+  return /\b(?:function|class)\b/.test(normalized.split('(')[0]);
+}
+
+// Reads symbols.json through the existing readArtifact cache (no new file reads, no new
+// cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
+// to [] so callers can render an outline block unconditionally.
+export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
+  if (!filePath) {
+    return Object.freeze([]);
+  }
+
+  const absoluteRoot = path.resolve(rootDir);
+  const symbolsArtifact = await readArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols);
+  const safeSymbolsArtifact = ensureArtifact(symbolsArtifact);
+  if (safeSymbolsArtifact.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    return Object.freeze([]);
+  }
+
+  const rows = (safeSymbolsArtifact.items ?? [])
+    .filter((item) => item?.filePath === filePath && item?.line !== null && item?.line !== undefined)
+    .filter((item) => item?.type !== 'callable' || isFunctionLikeSignature(item?.signature))
+    .sort((a, b) => a.line - b.line);
+
+  const seenNames = new Set();
+  const deduped = [];
+  for (const item of rows) {
+    if (seenNames.has(item.name)) {
+      continue;
+    }
+    seenNames.add(item.name);
+    deduped.push(item);
+  }
+
+  return Object.freeze(
+    deduped.slice(0, limit).map((item) => Object.freeze({
+      line: item.line,
+      name: item.name,
+      type: item.type,
+      signature: item.signature ?? null,
+    })),
+  );
+}
+
 async function readArtifact(rootDir, artifactName) {
   const artifactPath = getArtifactPath(path.resolve(rootDir), artifactName);
 

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -28,7 +28,7 @@ const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '
 const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
 const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md', '.sh']);
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
-const INDEX_SCHEMA_VERSION = 6;
+export const INDEX_SCHEMA_VERSION = 7;
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const INDEX_PARSE_BATCH_SIZE = 8;
 const MAX_IMPORTER_HOPS = 2;
@@ -395,6 +395,62 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
 
 // ── Query Index ──
 
+// The `callable` symbol regex matches any `const x = (`, so it also captures plain
+// parenthesised expressions such as `const rows = (items ?? [])`. Harmless for fuzzy
+// ranking, misleading in an outline that is read as a map of the file's API. Those rows
+// stay in symbols.json and are dropped here instead.
+function isFunctionLikeSignature(signature) {
+  const normalized = String(signature ?? '');
+  // computeSignature only appends `=>` directly after a balanced parameter list, so a
+  // trailing arrow is a reliable marker and body text that merely contains one is not.
+  if (normalized.endsWith('=>')) {
+    return true;
+  }
+  // `function`/`class` must belong to the declaration head, not to body text the bounded
+  // scan happened to include.
+  return /\b(?:function|class)\b/.test(normalized.split('(')[0]);
+}
+
+// Reads symbols.json through the existing readArtifact cache (no new file reads, no new
+// cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
+// to [] so callers can render an outline block unconditionally.
+export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
+  if (!filePath) {
+    return Object.freeze([]);
+  }
+
+  const absoluteRoot = path.resolve(rootDir);
+  const symbolsArtifact = await readArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols);
+  const safeSymbolsArtifact = ensureArtifact(symbolsArtifact);
+  if (safeSymbolsArtifact.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    return Object.freeze([]);
+  }
+
+  const rows = (safeSymbolsArtifact.items ?? [])
+    .filter((item) => item?.filePath === filePath && item?.line !== null && item?.line !== undefined)
+    .filter((item) => item?.type !== 'callable' || isFunctionLikeSignature(item?.signature))
+    .sort((a, b) => a.line - b.line);
+
+  const seenNames = new Set();
+  const deduped = [];
+  for (const item of rows) {
+    if (seenNames.has(item.name)) {
+      continue;
+    }
+    seenNames.add(item.name);
+    deduped.push(item);
+  }
+
+  return Object.freeze(
+    deduped.slice(0, limit).map((item) => Object.freeze({
+      line: item.line,
+      name: item.name,
+      type: item.type,
+      signature: item.signature ?? null,
+    })),
+  );
+}
+
 export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
   if (!query || !query.trim()) return [];
   if (limit <= 0) return Object.freeze([]);
@@ -1588,24 +1644,169 @@ async function collectFiles(scanRoots) {
   return result;
 }
 
-function extractScriptContent(filePath, content) {
-  if (!filePath.endsWith('.vue')) return content;
-  const allMatches = [...content.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)];
-  if (allMatches.length === 0) return '';
-  return allMatches.map((m) => m[1]).join('\n');
+function findScriptClose(content, startIndex) {
+  const lower = content.toLowerCase();
+  let state = 'normal';
+  let escaped = false;
+  let templateExpressionDepth = 0;
+
+  for (let index = startIndex; index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+
+    if (state === 'line-comment') {
+      if (char === '\n') state = 'normal';
+      continue;
+    }
+    if (state === 'block-comment') {
+      if (char === '*' && next === '/') {
+        index += 1;
+        state = 'normal';
+      }
+      continue;
+    }
+    if (state === 'single' || state === 'double' || state === 'template') {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (state === 'single' && char === "'") state = 'normal';
+      else if (state === 'double' && char === '"') state = 'normal';
+      else if (state === 'template') {
+        if (char === '`' && templateExpressionDepth === 0) state = 'normal';
+        else if (char === '{' && content[index - 1] === '$') templateExpressionDepth += 1;
+        else if (char === '}' && templateExpressionDepth > 0) templateExpressionDepth -= 1;
+      }
+      continue;
+    }
+
+    if (lower.startsWith('</script>', index)) return index;
+    if (char === '/' && next === '/') {
+      state = 'line-comment';
+      index += 1;
+    } else if (char === '/' && next === '*') {
+      state = 'block-comment';
+      index += 1;
+    } else if (char === "'") state = 'single';
+    else if (char === '"') state = 'double';
+    else if (char === '`') state = 'template';
+  }
+
+  return -1;
 }
 
-function extractSymbols(filePath, content) {
+export function extractScriptContent(filePath, content) {
+  if (!filePath.endsWith('.vue')) {
+    return content;
+  }
+
+  // Mask instead of extract: same length as `content`, non-script chars replaced by a
+  // space (newlines kept), so offsets stay 1:1 with the file on disk. See buildIndex.js.
+  const masked = content.replace(/[^\n]/g, ' ').split('');
+  let foundAny = false;
+  const startTagPattern = /<script[^>]*>/gi;
+  for (const match of content.matchAll(startTagPattern)) {
+    const bodyStart = match.index + match[0].length;
+    const bodyEnd = findScriptClose(content, bodyStart);
+    if (bodyEnd !== -1) {
+      foundAny = true;
+      for (let i = bodyStart; i < bodyEnd; i += 1) {
+        masked[i] = content[i];
+      }
+    }
+  }
+  if (!foundAny) return '';
+  return masked.join('');
+}
+
+function computeLineStarts(content) {
+  const starts = [0];
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === '\n') {
+      starts.push(index + 1);
+    }
+  }
+  return starts;
+}
+
+function lineNumberForIndex(lineStarts, index) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (lineStarts[mid] <= index) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return low + 1;
+}
+
+// Display string only, not a parse: scan forward from the start of the matched line to the
+// `)` that closes the parameter list, or to end-of-line when the line opens no paren. Depth
+// is tracked rather than stopping at the first `)`, otherwise a default-valued parameter
+// truncates mid-expression (`function f({ root = process.cwd() } = {})` would cut at the
+// `)` of `process.cwd()`). The scan is capped at 400 chars so a malformed file cannot walk
+// the whole buffer.
+function computeSignature(content, lineStartIndex) {
+  const boundedEnd = Math.min(content.length, lineStartIndex + 400);
+  let sliceEnd = boundedEnd;
+  let depth = 0;
+  let sawOpenParen = false;
+  for (let index = lineStartIndex; index < boundedEnd; index += 1) {
+    const char = content[index];
+    if (char === '(') {
+      depth += 1;
+      sawOpenParen = true;
+    } else if (char === ')') {
+      depth -= 1;
+      if (sawOpenParen && depth <= 0) {
+        sliceEnd = index + 1;
+        break;
+      }
+    } else if (char === '\n' && !sawOpenParen) {
+      sliceEnd = index;
+      break;
+    }
+  }
+
+  // Keep a trailing `=>` so an arrow function stays distinguishable from an ordinary
+  // parenthesised expression. getFileOutline relies on that to filter outline noise.
+  const arrowMatch = /^\s*=>/.exec(content.slice(sliceEnd, Math.min(content.length, sliceEnd + 8)));
+  if (arrowMatch) {
+    sliceEnd += arrowMatch[0].length;
+  }
+
+  const collapsed = content.slice(lineStartIndex, sliceEnd).replace(/\s+/g, ' ').trim();
+  if (collapsed.length <= 200) {
+    return collapsed;
+  }
+  return `${collapsed.slice(0, 199)}…`;
+}
+
+export function extractSymbols(filePath, content) {
   const out = [];
-  const addSymbol = (name, type) => {
+  const lineStarts = computeLineStarts(content);
+  const addSymbol = (name, type, matchIndex = null) => {
     if (!name) return;
-    out.push({ name, type, filePath });
+    if (matchIndex === null) {
+      out.push({ name, type, filePath, line: null, signature: null });
+      return;
+    }
+    const line = lineNumberForIndex(lineStarts, matchIndex);
+    const signature = computeSignature(content, lineStarts[line - 1]);
+    out.push({ name, type, filePath, line, signature });
   };
   const addMatches = (regex, type, idx = 1) => {
     for (const match of content.matchAll(regex)) {
       const name = match[idx];
       if (!name) continue;
-      addSymbol(name, type);
+      addSymbol(name, type, match.index);
     }
   };
 
@@ -1628,7 +1829,7 @@ function extractSymbols(filePath, content) {
     for (const part of (match[1] ?? '').split(',').map((x) => x.trim()).filter(Boolean)) {
       const parsed = part.match(/^([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?$/);
       if (!parsed) continue;
-      addSymbol(parsed[2] ?? parsed[1], 'named-export');
+      addSymbol(parsed[2] ?? parsed[1], 'named-export', match.index);
     }
   }
 

package/templates/.claude/ukit/index/query-index.mjs

@@ -11,14 +11,19 @@ import {
 const {
   queryCodeIndex,
   buildCodeIndex,
+  getFileOutline,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
   getIndexArtifactGeneratedAt,
 } = indexCore;
 
+const OUTLINE_TOP_FILES_LIMIT = 3;
+const OUTLINE_SYMBOLS_LIMIT = 12;
+
 const args = process.argv.slice(2);
 const rootDir = getRootDir(args);
 const limitArg = readFlagValue(args, '--limit');
 const limit = Number.parseInt(limitArg ?? '5', 10);
+const showOutline = !args.includes('--no-outline');
 const query = collectPositionalArgs(args, ['--root', '--limit']);
 
 if (!query) {
@@ -32,6 +37,7 @@ if (!query) {
     indexGeneratedAtMs,
     query,
     limit: effectiveLimit,
+    showOutline,
   });
   const cached = await readRecentCacheEntry(cachePath, requestKey, {
     maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
@@ -66,10 +72,39 @@ if (!query) {
       if ((item.reasons ?? []).length > 0) {
         console.log(`   reasons: ${item.reasons.join(', ')}`);
       }
+      if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
+        await printOutlineForFile(rootDir, item.filePath);
+      }
     }
   }
 }
 
+async function printOutlineForFile(root, filePath) {
+  if (typeof getFileOutline !== 'function') {
+    return;
+  }
+  const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity });
+  if (outline.length === 0) {
+    return;
+  }
+
+  const shown = outline.slice(0, OUTLINE_SYMBOLS_LIMIT);
+  const remaining = outline.length - shown.length;
+  const labels = shown.map((item) => String(item.line));
+  if (remaining > 0) {
+    labels.push(`+${remaining}`);
+  }
+  const labelWidth = Math.max(...labels.map((label) => label.length)) + 1;
+
+  console.log('   outline:');
+  for (const item of shown) {
+    console.log(`   ${String(item.line).padStart(labelWidth)}: ${item.signature ?? item.name}`);
+  }
+  if (remaining > 0) {
+    console.log(`   ${`+${remaining}`.padStart(labelWidth)} more symbols`);
+  }
+}
+
 async function ensureFreshIndex({ rootDir, logPrefix }) {
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = lastRefreshMs === null
@@ -102,11 +137,13 @@ function buildQueryRequestKey({
   indexGeneratedAtMs = null,
   query = '',
   limit = 5,
+  showOutline = true,
 } = {}) {
-  return buildCompactMachineKey('query-v1', {
+  return buildCompactMachineKey('query-v2', {
     indexGeneratedAtMs,
     query: String(query || '').trim(),
     limit: Number(limit),
+    showOutline: Boolean(showOutline),
   });
 }
 

package/templates/.claude/ukit/index/resolve-context.mjs

@@ -11,16 +11,20 @@ import {
 const {
   resolveContext,
   buildCodeIndex,
+  getFileOutline,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
   getIndexArtifactGeneratedAt,
 } = indexCore;
 const CONTEXT_DISPLAY_LIMIT = 2;
 const CONTEXT_REASON_LIMIT = 2;
+const OUTLINE_TOP_FILES_LIMIT = 3;
+const OUTLINE_SYMBOLS_LIMIT = 12;
 
 const args = process.argv.slice(2);
 const rootDir = getRootDir(args);
 const targetFile = readFlagValue(args, '--target');
 const taskType = readFlagValue(args, '--type');
+const showOutline = !args.includes('--no-outline');
 const intent = collectPositionalArgs(args, ['--root', '--target', '--type']);
 const effectiveIntent = deriveHelperIntent({ intent, targetFile });
 
@@ -57,7 +61,7 @@ if (!intent && !targetFile) {
     });
   }
 
-  printContextResult(result);
+  await printContextResult(result, { rootDir, showOutline });
 }
 
 async function ensureFreshIndex({ rootDir, logPrefix }) {
@@ -217,17 +221,48 @@ function unique(values = []) {
   return [...new Set(values.filter(Boolean))];
 }
 
-function printContextResult(result) {
+async function printContextResult(result, { rootDir, showOutline } = {}) {
   console.log('[ukit:context]');
   console.log(`taskType: ${result.taskType}`);
   console.log(`budget: ${result.contextBudget.minFiles}-${result.contextBudget.maxFiles} files`);
   printContextGroup('primaryTargets', result.primaryTargets, result.explanations?.primaryTargets);
+  if (showOutline) {
+    for (const filePath of (result.primaryTargets ?? []).slice(0, OUTLINE_TOP_FILES_LIMIT)) {
+      await printOutlineForFile(rootDir, filePath);
+    }
+  }
   printContextGroup('sharedAbstractions', result.sharedAbstractions, result.explanations?.sharedAbstractions);
   printContextGroup('analogFiles', result.analogFiles, result.explanations?.analogFiles);
   printContextGroup('relatedTests', result.relatedTests, result.explanations?.relatedTests);
   printContextGroup('styleFiles', result.styleFiles, result.explanations?.styleFiles);
 }
 
+async function printOutlineForFile(root, filePath) {
+  if (typeof getFileOutline !== 'function') {
+    return;
+  }
+  const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity });
+  if (outline.length === 0) {
+    return;
+  }
+
+  const shown = outline.slice(0, OUTLINE_SYMBOLS_LIMIT);
+  const remaining = outline.length - shown.length;
+  const labels = shown.map((item) => String(item.line));
+  if (remaining > 0) {
+    labels.push(`+${remaining}`);
+  }
+  const labelWidth = Math.max(...labels.map((label) => label.length)) + 1;
+
+  console.log('   outline:');
+  for (const item of shown) {
+    console.log(`   ${String(item.line).padStart(labelWidth)}: ${item.signature ?? item.name}`);
+  }
+  if (remaining > 0) {
+    console.log(`   ${`+${remaining}`.padStart(labelWidth)} more symbols`);
+  }
+}
+
 function printContextGroup(label, filePaths = [], explanations = []) {
   console.log(`${label}: ${formatCompactDisplayList(filePaths)}`);
 

package/templates/AGENTS.md

@@ -37,6 +37,11 @@ For any task that needs code context:
 3. For bug signatures:
    - `node .claude/ukit/index/triage.mjs "<error signature>"`
 4. Open only the **top 1-3 suspect files first**, then widen if needed.
+   `query-index` and `resolve-context` print an `outline:` block (`line: signature`) for the
+   top suspects. Use it to jump straight to the relevant region with
+   `Read(file, offset=<line>)` instead of reading the whole file.
+   The outline locates code; it does not describe behaviour. **Any code you are about to
+   change must still be read.**
 5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
 For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.

package/templates/CLAUDE.md

@@ -37,6 +37,11 @@ For any task that needs code context:
 3. For bug signatures:
    - `node .claude/ukit/index/triage.mjs "<error signature>"`
 4. Open only the **top 1-3 suspect files first**, then widen if needed.
+   `query-index` and `resolve-context` print an `outline:` block (`line: signature`) for the
+   top suspects. Use it to jump straight to the relevant region with
+   `Read(file, offset=<line>)` instead of reading the whole file.
+   The outline locates code; it does not describe behaviour. **Any code you are about to
+   change must still be read.**
 5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
 For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.