@ngockhoale/ukit 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.9 - 2026-08-28
+
+Retuning UKit's context budget used to mean editing five scattered places and hand-syncing two
+of them. It is now **three numbers in one file**, and everything else is derived at install time.
+
+The shipped defaults also move up for a 1M context window: compaction is recommended at 150,000
+estimated tokens (was 50,000) and the hard cap sits at 500,000 — half the window (was 220,000).
+
+### Changed
+
+- **`compact.tokenThreshold` / `compact.hardCapTokens` / `compact.autoCompactWindowRatio` in
+  `.ukit/storage/config.json` are now the only knobs.** New `src/core/compact/contextBudget.js`
+  reads them and derives the rest, so the defaults in `runtimeConfig.js` and
+  `compact/threshold.js` no longer carry their own copies of the number. Edit the three values,
+  rerun `ukit install`, and the whole budget follows. Documented in README →
+  *Retuning The Context Budget (maintainers)*, including a window→cap sizing table, because the
+  new 500,000 default sits **above** a 200k or 256k model's window, where the gate could never fire.
+- **New defaults:** `tokenThreshold` 50,000 → **150,000**; `hardCapTokens` 220,000 → **500,000**;
+  auto-compact fires at **70%** of the cap → 350,000.
+
+### Fixed
+
+- **omp auto-compact had silently drifted out of sync.** `.omp/config.yml`'s
+  `compaction.thresholdTokens` was still 180,000 while Claude Code's
+  `CLAUDE_CODE_AUTO_COMPACT_WINDOW` had moved on — the two were separate hand-maintained numbers
+  with nothing pinning them together. Both are now rendered from the same derived value at
+  install time, so **omp and Claude Code auto-compact at the same point** and cannot drift apart
+  again.
+- **`ompDocsSync > historical records are untouched by this cycle` failed on every new plan doc.**
+  The guard compared *all* changes under `docs/plans/` and friends against an old cycle's base
+  commit, so the first plan added afterwards (2.2.8's) tripped it permanently. Narrowed to
+  `--diff-filter=MDR`: rewriting, deleting or renaming a historical record still fails; adding a
+  new plan does not.
+
+## 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/README.md

@@ -114,6 +114,36 @@ For maintainers, the runtime is inspectable with:
 
 Normal teammates should still only need **`ukit install`**.
 
+## Retuning The Context Budget (maintainers)
+
+Switching to a model with a different context window is a **three-number edit in one file**:
+`templates/ukit/storage/config.json` → `compact`.
+
+| Key | Default | What it means |
+| --- | --- | --- |
+| `tokenThreshold` | `150000` | Soft advisory. Past this UKit starts recommending compaction. |
+| `hardCapTokens` | `500000` | Absolute ceiling — 50% of a 1M window. `context-hardcap-gate` blocks Edit/Write/Bash here. |
+| `autoCompactWindowRatio` | `0.7` | Auto-compact fires at this fraction of the cap (→ `350000`). Must be `< 1`. |
+
+Everything else is derived — do **not** hand-edit these:
+
+- `.claude/settings.json` → `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW`
+- `.omp/config.yml` → `compaction.thresholdTokens`
+- the code-side defaults in `src/core/runtimeConfig.js` and `src/core/compact/threshold.js`
+
+They are all rendered/read from the three keys above via `src/core/compact/contextBudget.js`.
+Edit the three numbers, rerun **`ukit install`**, and Claude Code and omp both follow.
+
+`hardCapTokens` must stay **below the model's real context window**, otherwise the API rejects
+the request before the gate can ever fire. Sizing at 50% of the window keeps room for the
+response plus the estimator's own undercount:
+
+| Model window | `hardCapTokens` | derived auto-compact |
+| --- | --- | --- |
+| 1M | `500000` | `350000` |
+| 256k | `128000` | `89600` |
+| 200k | `100000` | `70000` |
+
 ## Installer Behavior
 
 - idempotent install (safe to rerun)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.7",
+  "version": "2.2.9",
   "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/core/compact/contextBudget.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// The shipped compact.tokenThreshold / compact.hardCapTokens / compact.autoCompactWindowRatio
+// trio is the ONLY place the context budget is written down. Every other number — the
+// code-side defaults, CLAUDE_CODE_AUTO_COMPACT_WINDOW in .claude/settings.json, and
+// compaction.thresholdTokens in .omp/config.yml — is read or derived from here, so retuning
+// UKit for a different model context window is a three-number edit in
+// templates/ukit/storage/config.json and nothing else.
+const SHIPPED_CONFIG_URL = new URL('../../../templates/ukit/storage/config.json', import.meta.url);
+
+// Only reachable if the package ships without its own templates. Deliberately conservative:
+// a 200k model survives these, a 1M model merely compacts earlier than it had to.
+const EMERGENCY_BUDGET = {
+  tokenThreshold: 50_000,
+  hardCapTokens: 160_000,
+  autoCompactWindowRatio: 0.7,
+};
+
+// Auto-compact must land strictly below hardCapTokens so the client heals itself before
+// context-hardcap-gate starts refusing Edit/Write/Bash; a ratio >= 1 would invert that and is
+// treated as a typo rather than honoured.
+export function deriveAutoCompactWindow(hardCapTokens, ratio) {
+  const safeRatio = Number.isFinite(ratio) && ratio > 0 && ratio < 1
+    ? ratio
+    : EMERGENCY_BUDGET.autoCompactWindowRatio;
+  return Math.round(hardCapTokens * safeRatio);
+}
+
+let cachedBudget = null;
+
+export function loadShippedCompactBudget() {
+  if (cachedBudget) {
+    return cachedBudget;
+  }
+
+  let compact = EMERGENCY_BUDGET;
+  try {
+    compact = JSON.parse(readFileSync(fileURLToPath(SHIPPED_CONFIG_URL), 'utf8')).compact ?? {};
+  } catch {
+    compact = EMERGENCY_BUDGET;
+  }
+
+  const tokenThreshold = Number.isFinite(compact.tokenThreshold)
+    ? compact.tokenThreshold
+    : EMERGENCY_BUDGET.tokenThreshold;
+  const hardCapTokens = Number.isFinite(compact.hardCapTokens)
+    ? compact.hardCapTokens
+    : EMERGENCY_BUDGET.hardCapTokens;
+
+  cachedBudget = {
+    tokenThreshold,
+    hardCapTokens,
+    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, compact.autoCompactWindowRatio),
+  };
+  return cachedBudget;
+}

package/src/core/compact/threshold.js

@@ -2,6 +2,7 @@ import { readJsonIfExists, writeJson } from '../fileOps.js';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
+import { loadShippedCompactBudget } from './contextBudget.js';
 
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
 const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
@@ -427,7 +428,10 @@ function computeEstimatedTotalTokens({
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const softThreshold = Math.max(
+    1,
+    finiteNumber(config?.compact?.tokenThreshold, loadShippedCompactBudget().tokenThreshold),
+  );
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
 

package/src/core/runtimeConfig.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { buildRuntimePaths } from './runtimePaths.js';
+import { loadShippedCompactBudget } from './compact/contextBudget.js';
 
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require('../../package.json');
@@ -70,7 +71,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     compact: {
       enabled: true,
-      tokenThreshold: 50_000,
+      tokenThreshold: loadShippedCompactBudget().tokenThreshold,
       contextRotDetection: true,
       askBeforeDrop: true,
       agentContext: {

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/src/render/buildVariables.js

@@ -1,3 +1,5 @@
+import { loadShippedCompactBudget } from '../core/compact/contextBudget.js';
+
 const CODEGRAPH_SECTION = `
 ## CodeGraph Integration (active)
 
@@ -12,7 +14,15 @@ To disable: rerun \`ukit install\` without \`--with-codegraph\`.
 `;
 
 export function buildTemplateVariables({ projectContext, stackContext, packageVersion, providerContext, withCodegraph = false }) {
+  // Derived, never hand-written: .claude/settings.json is read by Claude Code itself and so
+  // cannot consult .ukit/storage/config.json at runtime. Baking the window in here keeps
+  // compact.hardCapTokens the single number that retunes both.
+  const { autoCompactWindow } = loadShippedCompactBudget();
+
   return {
+    compact: {
+      autoCompactWindow: String(autoCompactWindow),
+    },
     project: {
       name: projectContext.project.name,
       root: projectContext.project.root,

package/templates/.claude/settings.json

@@ -11,7 +11,7 @@
   "defaultView": "chat",
   "autoCompactEnabled": true,
   "env": {
-    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "180000"
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "{{compact.autoCompactWindow}}"
   },
   "permissions": {
     "defaultMode": "bypassPermissions",

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/.claude/ukit/runtime/compact-threshold.mjs

@@ -434,7 +434,7 @@ function computeEstimatedTotalTokens({
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 150_000));
   const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
   // Deliberately NOT coupled to hardThreshold: this is an absolute ceiling, so raising
@@ -442,13 +442,15 @@ export function buildCompactThresholds(config = {}) {
   //
   // Must stay BELOW the model's real context window or the cap is unreachable: the API
   // rejects the request with "input exceeds the context window" long before an estimate
-  // climbing toward a higher number ever trips this. 220_000 is sized for a 256k window
-  // and leaves headroom for the response plus the estimator's own undercount. On a 200k
-  // model this default sits ABOVE the window, so the gate can never fire and is dead code
-  // in exactly the situation it exists to prevent — set compact.hardCapTokens to 160_000
-  // or lower for those. Pair it with env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, which must stay
-  // strictly below this cap so the client auto-compacts before the gate blocks tools.
-  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 220_000));
+  // climbing toward a higher number ever trips this. 500_000 is half of a 1M window, which
+  // leaves ample headroom for the response plus the estimator's own undercount. On any
+  // smaller model this default sits ABOVE the window, so the gate can never fire and is
+  // dead code in exactly the situation it exists to prevent — set compact.hardCapTokens to
+  // 100_000 (200k model) or 128_000 (256k model) for those. Both
+  // env.CLAUDE_CODE_AUTO_COMPACT_WINDOW and omp's compaction.thresholdTokens are rendered
+  // from this number at install time (70% of it), so the client auto-compacts before the
+  // gate blocks tools without anyone hand-syncing a second value.
+  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 500_000));
 
   return {
     softThreshold,

package/templates/.omp/config.yml

@@ -78,8 +78,11 @@ memory:
   backend: off
 
 # Auto-compact must trigger BEFORE context-hardcap-gate.sh starts blocking tool
-# calls (compact.hardCapTokens, default 220000). Mirrors the Claude Code value
-# env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000 in templates/.claude/settings.json.
+# calls (compact.hardCapTokens, default 500000). Rendered at install time from the
+# same derived number as env.CLAUDE_CODE_AUTO_COMPACT_WINDOW in
+# templates/.claude/settings.json (70% of hardCapTokens), so omp and Claude Code
+# cannot drift apart and retuning both is a single edit to
+# templates/ukit/storage/config.json.
 #
 # Key VERIFIED against omp v17.4.2 (2026-08-22): `compaction.thresholdTokens` is a
 # fixed token limit for context maintenance and overrides the percentage threshold
@@ -88,4 +91,4 @@ memory:
 # omp rejects it outright (`omp config get compact.autoCompactWindow` → "Unknown
 # setting"), so auto-compact never moved off omp's default. See PLAN.md §3 D13.
 compaction:
-  thresholdTokens: 180000
+  thresholdTokens: {{compact.autoCompactWindow}}

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.

package/templates/docs/AI_HANDOFF/RULES.md

@@ -79,8 +79,8 @@ Next: <bước kế tiếp chính xác>
 - Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
 - Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
 - Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
-- Vượt `compact.hardCapTokens` (mặc định 220k, cỡ cho context window 256k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
-- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 180000` < `hardCapTokens` (220k), nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
+- Vượt `compact.hardCapTokens` (mặc định 500k = 50% của context window 1M) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
+- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` = 70% của `hardCapTokens` (mặc định 350000 < 500k), render lúc install, nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
 - Sửa một trong hai số đó thì phải giữ `autoCompactWindow < hardCapTokens`. Đảo thứ tự là deadlock: gate chặn tool trước → transcript ngừng lớn → ngưỡng auto-compact không bao giờ tới. `tests/core/autoCompactWindow.test.js` khóa bất biến này.
 
 ### Git

package/templates/ukit/storage/config.json

@@ -8,8 +8,9 @@
   },
   "compact": {
     "enabled": true,
-    "tokenThreshold": 50000,
-    "hardCapTokens": 220000,
+    "tokenThreshold": 150000,
+    "hardCapTokens": 500000,
+    "autoCompactWindowRatio": 0.7,
     "hardCapBlock": true,
     "hardCapGraceCalls": 10,
     "contextRotDetection": true,
@@ -394,7 +395,8 @@
     "compact": {
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
-      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 220000 token ước lượng, cỡ cho context window 256k). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model, nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn — model 200k thì hạ xuống 160000 hoặc thấp hơn. Đi kèm env.CLAUDE_CODE_AUTO_COMPACT_WINDOW trong .claude/settings.json (mặc định 180000), số đó phải nhỏ hơn ngưỡng này để client tự auto-compact trước khi gate chặn tool.",
+      "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 500000 token ước lượng = 50% của context window 1M). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model, nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn — model 200k thì hạ xuống 100000, model 256k thì 128000. Cả env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) lẫn compaction.thresholdTokens (.omp/config.yml) đều được SUY RA từ số này khi chạy ukit install, nên chỉ cần sửa ở đây rồi cài lại là auto-compact của cả Claude Code và omp đổi theo.",
+      "autoCompactWindowRatio": "Auto-compact chạy ở bao nhiêu phần của hardCapTokens (mặc định 0.7 → 350000). Phải < 1 để client tự compact TRƯỚC khi context-hardcap-gate chặn tool; số càng nhỏ thì compact càng sớm và càng nhiều đệm an toàn.",
       "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm.",
       "hardCapGraceCalls": "Số tool call được phép chạy tiếp sau khi vượt hardCapTokens KHI docs/AI_HANDOFF/RUN.md còn run dở (mặc định 10). Dùng để run kịp commit + ghi cursor + push rồi mới bị chặn, thay vì chết giữa lúc đang Edit. Hết grace là chặn cứng như cũ. Budget tính theo mỗi đợt vượt cap, chỉ reset khi ước lượng token thật sự giảm (có compact thật) — không reset theo wave.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",